Python库路径设置：让模块导入不再出错

在日常开发中，经常会遇到 Python 找不到自定义模块的问题。比如你在项目里写了个工具脚本，想在另一个文件里 import，结果一运行就报错 ModuleNotFoundError。这种情况其实大多和库路径设置有关。

Python 是怎么找模块的？

Python 在导入模块时会按顺序查找 sys.path 列表中的路径。这个列表包含了当前目录、标准库路径、第三方包安装位置等。你可以这样查看：

import sys
for path in sys.path:
    print(path)

你会发现第一项通常是空字符串，代表当前执行脚本所在的目录。如果模块不在这些路径下，自然就导入失败了。

临时添加路径：适合调试

最简单的办法是在代码里临时修改 sys.path。比如你的模块放在项目下的 libs/ 目录：

import sys
sys.path.append('./libs')

import mymodule  # 现在可以正常导入了

这种方法简单直接，适合测试或小项目。但不推荐用于生产环境，毕竟硬编码路径不够优雅。

使用 PYTHONPATH 环境变量

更灵活的方式是通过环境变量控制搜索路径。在 Linux 或 macOS 上：

export PYTHONPATH=$PYTHONPATH:/path/to/your/libs
python your_script.py

Windows 用户可以用：

set PYTHONPATH=%PYTHONPATH%;C:\path\to\your\libs
python your_script.py

这样就不需要改动代码，适合团队协作，每个人可以根据本地结构配置。

创建可安装的包

如果你写的模块会被多个项目使用，建议打包成可安装的库。在模块目录下加一个 setup.py：

from setuptools import setup, find_packages

setup(
    name='mymodule',
    version='0.1',
    packages=find_packages(),
)

然后运行：

pip install -e .

这个 -e 参数表示“开发模式”，改代码后不用重新安装。安装后 anywhere 都能 import 这个模块。

虚拟环境中的路径管理

实际项目中通常用虚拟环境隔离依赖。激活环境后，sys.path 会自动包含该环境的 site-packages。你安装的包都会被放在这里，路径问题也就顺带解决了。

但如果项目结构复杂，比如有多个子模块分布在不同目录，配合 __init__.py 和相对导入会更稳妥。

别忘了 __init__.py

有些老版本 Python 要求包目录下必须有 __init__.py 文件才会被识别为模块路径。虽然 Python 3.3+ 支持隐式命名空间包，但加上这个文件仍能避免不少意外。

比如目录结构是：

project/
├── main.py
└── utils/
    └── __init__.py
    └── helpers.py

在 main.py 中就能顺利导入：from utils.helpers import something。

路径设置看着小，处理不好会影响整个项目的组织方式。花点时间理清机制，后面少踩很多坑。