Adam Chow's Life Journals

Appearance

搞定 Python 包的安装与定位，看这一篇就够了！ ​

如果你在 Python 开发中经常遇到以下三个环境配置问题，这篇文章将为你提供解决思路：

  1. 明明已经安装了 pip，为什么运行时却报找不到可执行文件？
  2. 为什么 import 某个模块时会报 ``ModuleNotFound？
  3. 为什么相同的脚本在 Pycharm IDE 中能正常运行，但在命令行环境中却执行失败？

知识点一 - Python 是如何寻找包的？ ​

在个人开发环境中可能常常并存多个 Python 版本和虚拟环境，这给包管理带来了一定的复杂性。要准确定位和管理这些包，首先需要了解 Python 包的搜索机制。当 Python 解释器位于 $YOUR_PYTHON_INSTALL_PATH/bin/python 时，系统会按照以下优先级顺序搜索包：

  1. $YOUR_PYTHON_INSTALL_PATH/lib（标准库路径）
  2. $YOUR_PYTHON_INSTALL_PATH/lib/pythonX.Y/site-packages（三方库路径，X.Y 表示 Python 的主次版本号，如 2.7, 3.10）
  3. 当前脚本/项目的工作路径

在 Linux 系统中，系统默认的 Python 安装会将 $YOUR_PYTHON_INSTALL_PATH 设置为 /usr；而使用手动编译安装的 Python，其 $YOUR_PYTHON_INSTALL_PATH 则为 /usr/local。

需要特别关注的是三方库的版本依赖问题：由于不同 Python 版本的三方库路径各不相同，假如从 Python 3.9 升级到 3.10 时，原有的三方库将无法被新版本识别。尽管可以通过复制整个库文件夹来快速迁移，但这种做法可能会引入潜在的兼容性问题，建议在正式环境中谨慎使用。

三个实用的执行路径相关的函数 ​

  • sys.executable：当前使用的 Python 解释器路径
  • sys.path：当前包的搜索路径列表
  • sys.prefix：当前使用的 $YOUR_PYTHON_INSTALL_PATH

使用 PYTHONPATH 环境变量添加搜索路径 ​

如果你的包路径不在 Python 默认的搜索路径列表中，可以将其添加到 PYTHONPATH 环境变量中。多个路径在 Linux/macOS 等类 Unix 系统中用冒号 (😃 分隔，在 Windows 系统中则使用分号 (😉 分隔。

然而，需要特别注意：应避免将不同 Python 版本的包路径添加到 PYTHONPATH 中。这是因为 PYTHONPATH 中的路径优先级高于默认搜索路径，如果你使用 Python 3，但通过 PYTHONPATH 环境变量添加了 Python 2 相关的包，这可能会导致兼容性问题。实际上，PYTHONPATH 中最好完全避免出现任何包含 /path/to/lib/pythonX.Y/site-packages 的路径。

与 PYTHONPATH 类似，系统还有一个重要的 PATH 环境变量，它专门用于定位可执行程序。当你在终端中执行命令 some_cmd 时，系统会按顺序扫描 PATH 中的每个目录，直到找到名为 some_cmd 的可执行文件。这就解释了为什么当你安装了新程序却收到"命令未找到"的错误时，通常需要检查该程序的安装目录是否已添加到 PATH 中。

知识点二 - Python 是如何安装包的？ ​

在当前的 Python 生态中，pip 是包管理的基石工具。即使你使用 pipenv 或 poetry 等高级包管理工具，它们的底层依然依赖于 pip。pip 的使用有两种方式：

  1. pip ...
  2. python -m pip ...

这两种方式在功能上基本等效，区别在于执行路径。第一种方式使用的是 pip 文件 shebang 中指定的 Python 解释器。具体来说，当 pip 的路径为 $YOUR_PYTHON_INSTALL_PATH/bin/pip 时，其对应的 Python 解释器路径应该为 $YOUR_PYTHON_INSTALL_PATH/bin/python。第二种方式则是显式指定使用特定的 Python 解释器，这个执行机制适用于所有 Python 的可执行程序。

在默认配置下，pip 遵循固定的安装路径规则：Python 包会被安装到 $YOUR_PYTHON_INSTALL_PATH/lib/pythonX.Y/site-packages 目录，可执行程序则安装到 $YOUR_PYTHON_INSTALL_PATH/bin 目录。

虚拟环境通过创建独立的 Python 环境来隔离不同项目的依赖包，从而避免依赖冲突。从技术实现上看，在路径 /path/to 下运行 virtualenv myenv 时，系统会：

  1. 将 Python 解释器复制到 /path/to/myenv/bin 目录下
  2. 创建必要的目录结构，包括 /path/to/myenv/lib 和 /path/to/myenv/lib/pythonX.Y/site-packages
  3. 提供激活脚本 activate

当执行 source /path/to/myenv/bin/activate 后，系统会将 /path/to/myenv/bin 添加到 PATH 环境变量的最前面，确保虚拟环境中的 Python 解释器优先被使用。这样，后续的包安装操作会将 $YOUR_PYTHON_INSTALL_PATH 指向 /path/to/myenv，这样就实现了项目依赖的有效隔离。

补充知识点 - 脚本运行方式对搜索路径的影响 ​

Python 包的导入机制主要依赖于 sys.path，而 sys.path 的配置又与 sys.executable 的路径密切相关。这种机制意味着，即便是同一段代码，不同的运行方式也可能因为 sys.path 的差异而产生不同的行为。为了深入理解这一特性，我们来分析一个典型的包导入场景。

考虑以下项目结构：

├── main.py
└── my_package
    ├── __init__.py
    ├── a.py
    └── b.py

main.py 的内容：

python
import my_package.a

print("I'm main")

a.py 的内容：

python
import sys

print("I'm a")
print(sys.path)

当我们在命令行中执行 python main.py 时，即采用直接运行的方式，输出结果如下：

shell
$ python main.py

I'm a
['/Users/adamzhou/Desktop/python_test_examples', ...]
I'm main

这里的直接运行意味着 Python 解释器将 main.py 作为程序的入口点，并将其 name 变量设置为 main。注意观察输出中的 sys.path，其第一个元素是脚本所在的目录路径。在这个例子中，脚本位于 /Users/adamzhou/Desktop/python_test_examples 目录下。

这就引出了一个有趣的问题：如果我们需要在 a.py 中导入同级的 b.py 模块 (其中只包含一行简单的 print("I'm b"))，应该采用什么样的导入语句才是最合适的？这个选择将直接影响到代码的可移植性和健壮性。

在使用直接导入语句 import b 进行测试时，我们获得了如下输出：

shell
$ python main.py

...
ModuleNotFoundError: No module named 'b'
$ python my_package/a.py

I'm b
I'm a
['/Users/adamzhou/Desktop/python_test_examples/my_package', ...]

main.py 执行失败的原因与 Python 的模块搜索机制有关：Python 解释器在导入模块时，会按照 sys.path 中的目录顺序逐一查找目标模块。由于 b.py 文件位于 /Users/adamzhou/Desktop/python_test_examples/my_package 目录下，而该目录并未包含在 sys.path 中，导致解释器无法定位模块 b，最终抛出 ModuleNotFoundError 异常。

当我们将导入语句修改为 from my_package import b 后，测试结果发生了变化：

shell
$ python main.py

I'm b
I'm a
['/Users/adamzhou/Desktop/python_test_examples', ...]
I'm main
$ python my_package/a.py

...
ModuleNotFoundError: No module named 'my_package'

这种情况下，main.py 能够成功执行是因为其所在目录的父级目录包含了 my_package，而 a.py 执行失败则是因为从 my_package 目录内部执行时，Python 解释器无法找到名为 my_package 的包。

祭出终极解决方案 ​

Python 项目中的导入路径问题可以通过统一的模块运行方式来解决。最佳实践是将主要运行逻辑集中在 main.py 中，而当需要运行子目录中的脚本时，应使用 python -m <module_name> 的方式。例如，在 a.py 中导入 b 模块时，应该使用 from my_package import b 的形式。下面是两种运行方式的对比：

shell
# 通过主入口运行
$ python main.py

I'm b
I'm a
['/Users/adamzhou/Desktop/python_test_examples', ...]
I'm main

# 以模块方式运行子目录脚本
$ python -m my_package.a

I'm b
I'm a
['/Users/adamzhou/Desktop/python_test_examples', ...]

这两种运行方式下的 sys.path 保持一致，第一个值都指向当前运行目录。使用 python -m 命令时，需要指定以点号分隔的完整模块路径，而不是文件系统路径。这种统一的导入方式让你可以在项目的任何位置使用相同的导入语法，这也是为什么 Django 官方文档推荐使用 myapp.models.users 这样的完整模块路径。

以模块方式运行有以下几个关键特性：

  • 自动执行父模块：系统会依次执行模块路径中的每一级父模块或包
  • 支持相对导入：你可以在模块中使用相对导入语法，这在直接运行脚本时是不支持的
  • 保持主模块特性：被执行模块的 name 值会设置为 main，因此仍可使用 if name == "main": 条件判断
  • 包的特殊处理：当运行一个包时 (python -m package_name)，系统会查找并执行该包目录下的 main.py 文件