Python模块搜索路径详解：sys.path配置与三种添加方法

简述

在某些情况下，执行 import 语句时 Python 无法定位到目标模块，此时解释器会抛出 ImportError 异常以提示错误。

那么，Python 解释器依据什么规则来查找模块所在的目录路径呢？

模块搜索路径

当尝试导入名为 hello 的模块时，解释器会优先检索内置模块。若未找到匹配项，则会在 sys.path 变量所定义的目录列表中，查找名为 hello.py 的文件。

sys.path 列表的初始内容源自以下位置：

包含输入脚本的目录（若未指定具体文件，则默认为当前工作目录） PYTHONPATH 环境变量（其格式为目录名列表，语法与 shell 的 PATH 变量一致） 与 Python 安装路径相关的默认值

>>> import sys
>>> sys.path
['', '/usr/local/lib/python35.zip', '/usr/local/lib/python3.5', '/usr/local/lib/python3.5/plat-linux',
 '/usr/local/lib/python3.5/lib-dynload', '/usr/local/lib/python3.5/site-packages']

注意：sys.path 列表中的空字符串 '' 代表当前目录，即当前正在执行的脚本所在的目录。

例如，在 /home/wang/workspace 目录下创建一个名为 hello.py 的模块文件，其内容如下：

print('Hello')

随后，尝试在 Python 环境中加载该模块：

>>> import os
>>> 
>>> os.getcwd() # 获取当前目录
'/home/wang'
>>> 
>>> import hello.py
...
ImportError: No module named 'hello'

遗憾的是，由于此时 sys.path 列表中并未包含 /home/wang/workspace 路径，Python 无法找到 hello 模块，进而引发 ImportError 错误。

添加模块搜索路径

为解决上述模块找不到的问题，我们需要手动添加模块搜索路径，具体可采用以下几种方式：

1. 动态增加路径

该方法仅在当前 Python 会话期间临时生效。对于非频繁使用的模块，这是较为推荐的做法，因为它避免了用次要模块的路径去污染全局的 PYTHONPATH 环境变量。

2. 修改 PYTHONPATH 变量

此方法可实现永久生效，适用于那些在多个程序中频繁调用的模块。这种方式会改变所有 Python 应用的搜索路径，因为每次启动 Python 时都会读取该环境变量，甚至不同版本的 Python 解释器也会受到此设置的影响。

3. 增加 .pth 文件

此方法同样永久生效，且操作最为简单，是官方推荐的方式。当 Python 遍历已知的库文件目录时，若遇到扩展名为 .pth 的文件，便会将其内部声明的路径自动添加到 sys.path 中，从而使 .pth 文件所指定的路径对 Python 运行环境可见。

动态增加路径

通过导入 sys 模块并调用其 append() 方法，可以在当前 Python 环境中动态添加搜索路径：

>>> import sys
>>> sys.path.append('/home/wang/workspace')

添加完成后，检查当前的搜索路径列表：

>>> sys.path
['', '/usr/local/lib/python35.zip', '/usr/local/lib/python3.5', '/usr/local/lib/python3.5/plat-linux',
 '/usr/local/lib/python3.5/lib-dynload', '/usr/local/lib/python3.5/site-packages', '/home/wang/workspace']
>>> 
>>> import hello
Hello

从输出结果可见，新路径已成功加入列表。此时再次执行导入操作，模块即可正常加载。

修改 PYTHONPATH 变量

打开并编辑用户家目录下的 bashrc 配置文件：

$ vim ~/.bashrc

将以下配置行追加到文件末尾：

export PYTHONPATH=$PYTHONPATH:/home/wang/workspace

配置修改后，务必重新加载 Shell 配置以生效。可以通过退出当前终端并重新启动，或在命令行中执行以下命令重新加载配置文件：

$ source ~/.bashrc # 或者 . ~/.bashrc 

增加 .pth 文件

在 Python 的 site-packages 目录下（例如 /usr/local/lib/python3.5/site-packages）创建一个扩展名为 .pth 的配置文件（例如命名为 extras.pth），并在文件中写入需要添加的路径：

/home/wang/workspace

总结

以上就是本文关于Python模块搜索路径代码详解的全部内容，希望对大家有所帮助。感兴趣的朋友可以继续参阅本站其他相关专题，如有不足之处，欢迎留言指出。感谢朋友们对本站的支持！