PYTHONPATH 是一个环境变量，它的作用告诉 Python 解释器，除了默认的库搜索路径（如 site-packages）之外，还应该去哪些目录里寻找模块（.py 文件）和包。

为什么需要配置 PYTHONPATH？

配置 PYTHONPATH 的主要目的是：

1. 组织和重用代码：你可以将项目中的公共模块或工具库放在一个单独的目录下，然后通过 PYTHONPATH 让所有项目都能引用它们,而无需安装到系统或虚拟环境中。
2. 方便测试：当你正在开发一个包，但尚未安装时（没有运行 setup.py install），可以通过 PYTHONPATH 将项目根目录添加到搜索路径中,从而在其他脚本中正确地导入该包。
3. 覆盖系统包：不推荐，但在某些特殊情况下，你可以通过 PYTHONPATH 让 Python 优先使用你自己的版本而不是系统自带的库。

PYTHONPATH 的工作原理

Python 在查找一个模块时,会按照以下顺序在一系列目录中搜索：

1. 程序的主目录：运行脚本的所在目录。
2. PYTHONPATH 目录：环境变量 PYTHONPATH 中列出的所有目录。
3. 标准库目录：Python 安装时自带的库路径。
4. 第三方包目录：通常是你虚拟环境中的 site-packages 目录。

只要你的模块或包位于上述任何一个路径中，Python 就能找到它。

如何配置 PYTHONPATH (不同平台和方法)

配置环境变量的方法因操作系统（Windows, macOS, Linux）和持久化需求（临时生效或永久生效）而异。

场景设定

为了方便演示,我们假设有以下目录结构：

/my_project
├── my_lib/
│   └── utils.py          # 我们想导入的模块
└── main.py               # 我们想运行的主脚本

my_lib/utils.py 的内容：

# my_lib/utils.py
def say_hello():
    print("Hello from my_lib.utils!")

main.py 的内容：

# main.py
from my_lib import utils
utils.say_hello()

当前问题：直接运行 python main.py 会报 ModuleNotFoundError: No module named 'my_lib'，因为 Python 不知道去哪里找 my_lib。

我们的目标就是通过配置 PYTHONPATH，让 Python 能找到 /my_project 这个目录，从而成功导入 my_lib。

临时配置（仅对当前终端会话有效）

这种方法适用于临时测试,不会影响你的系统环境。

在 Linux 或 macOS

使用 export 命令。

# 打开你的终端
# 进入到 /my_project 的父目录
cd /my_project
# 设置 PYTHONPATH，值为当前目录的路径
# 注意：路径之间用冒号 : 分隔
export PYTHONPATH=/my_project:$PYTHONPATH
# 现在可以成功运行脚本了
python main.py
# 输出: Hello from my_lib.utils!
# 关闭终端后，这个配置就失效了

$PYTHONPATH 的作用：这会将你新添加的路径 /my_project 放到 PYTHONPATH 的最前面，同时保留 PYTHONPATH 中原有的其他路径,避免覆盖。

在 Windows (命令提示符 cmd)

使用 set 命令。

# 打开命令提示符
# 进入到 /my_project 的父目录
cd C:\my_project
# 设置 PYTHONPATH，值为当前目录的路径
# 注意：路径之间用分号 ; 分隔
set PYTHONPATH=C:\my_project;%PYTHONPATH%
# 现在可以成功运行脚本了
python main.py
# 输出: Hello from my_lib.utils!
# 关闭命令提示符后，配置失效

在 Windows (PowerShell)

使用 $env: 语法。

# 打开 PowerShell
# 进入到 /my_project 的父目录
cd C:\my_project
# 设置 PYTHONPATH
$env:PYTHONPATH="C:\my_project;$env:PYTHONPATH"
# 现在可以成功运行脚本了
python main.py
# 输出: Hello from my_lib.utils!
# 关闭 PowerShell 后，配置失效

永久配置（对所有新终端会话生效）

这种方法会修改系统的环境变量配置,之后打开的任何新终端都会自动加载这个设置。

在 Linux 或 macOS

你需要修改 shell 的配置文件，通常是 ~/.bashrc, ~/.zshrc (对于 macOS Catalina 及更新版本) 或 ~/.profile。

1. 打开配置文件，对于使用 Zsh 的 macOS 用户：

   nano ~/.zshrc

2. 在文件末尾添加以下内容：

   # 设置 PYTHONPATH
   # 将 /path/to/your/my_project 替换成你的实际路径
   export PYTHONPATH="/path/to/your/my_project:$PYTHONPATH"

3. 保存并退出（在 nano 中是 Ctrl+X，Y，Enter）。
4. 重新加载配置文件，让当前终端也生效：

   source ~/.zshrc

   或者,直接关闭终端然后重新打开一个。

在 Windows

通过图形界面设置。

1. 在搜索栏中搜索 “编辑系统环境变量” 并打开。
2. 在弹出的 “系统属性” 窗口中，点击右下角的 “环境变量...” 按钮。
3. 在 “系统变量” (推荐) 或 “用户变量” 部分找到 PYTHONPATH 变量：
   • 如果已存在：点击 “编辑...”，在 “变量值” 的开头或结尾添加你的路径（如 C:\my_project），并用分号 与原有路径隔开。
   • 如果不存在：点击 “新建...”：
     • 变量名：PYTHONPATH
     • 变量值：C:\my_project
4. 点击 “确定” 保存所有弹出的窗口。
5. 重要：重新打开一个新的命令提示符或 PowerShell 窗口,配置才会生效。

替代方案：为什么不总是用 PYTHONPATH？

虽然 PYTHONPATH 很有用，但在现代 Python 开发中，我们通常有更好的选择,因为它有一些缺点：

• 全局污染：它会改变全局的 Python 模块搜索路径,可能会引入意想不到的模块冲突。
• 不明确：其他开发者看到你的代码时，无法直接看出依赖了哪些本地路径,需要去检查环境变量。
• 管理困难：在大型项目中，管理多个 PYTHONPATH 条目会很混乱。

更好的替代方案

1. 使用虚拟环境 (venv 或 conda) 这是 最推荐 的做法，虚拟环境会为你创建一个隔离的 Python 环境，你可以在这个环境中安装项目所需的包（包括本地开发的包）。

   # 创建虚拟环境
   python -m venv myenv
   # 激活虚拟环境
   # Windows
   myenv\Scripts\activate
   # macOS/Linux
   source myenv/bin/activate
   # 你可以将你的项目路径以 "可编辑" 模式安装
   pip install -e /path/to/your/my_project
   # 现在在任何地方运行 python main.py 都可以了
   # 只要虚拟环境是激活的

2. 使用 -m 标志运行模块 如果你的项目是一个包（包含 setup.py 或 pyproject.toml）,这是最标准的方式。

   # 假设你在 /my_project 目录下
   cd /my_project
   # -m 表示将后面的路径当作一个模块来运行
   python -m main

3. 使用 sys.path 在代码中临时修改 如果只是想在某个特定脚本中临时添加路径，而不想设置环境变量,可以在代码开头这样做：

   import sys
   import os
   # 将项目根目录添加到 sys.path 的最前面
   project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
   sys.path.insert(0, project_root)
   # 现在可以正常导入了
   from my_lib import utils
   utils.say_hello()

   注意：这是一种侵入式的方法,只在必要时使用。

对于绝大多数情况，请优先选择 虚拟环境。PYTHONPATH 是一个有用的工具，尤其是在需要快速测试未安装的包时,但应谨慎使用永久配置。