使用venv开发Python模块的PYTHONPATH最佳实践工作流

核心解决方案：使用pip开发模式安装 #

这是Python包开发的标准做法，完全不需要手动修改sys.path、activate脚本或.pth文件：

1. 激活你的venv：

source venv/bin/activate

2. 先卸载之前安装的正式版本（避免冲突）：

pip uninstall -y my_module

3. 以开发模式安装你的包：

pip install -e .

执行完以上步骤后，直接运行python -m my_module.src1 args就会自动加载src/my_module/下的开发文件，修改代码后无需重新安装，立即生效。

为什么这是最佳实践？ #

• 开发模式会在venv的site-packages目录中创建一个指向你本地src目录的软链接（或.pth文件），让Python优先加载开发目录的代码，而非正式安装版本。
• 完全兼容hatchling和pyproject.toml的src-layout结构，符合Python packaging规范。
• 无需额外的环境变量配置，激活venv后即可直接使用，团队协作时也无需共享额外的配置脚本。

为什么你之前的方法不推荐？ #

• 修改venv/bin/activate：venv是轻量可重建的（比如删除后重新创建），修改脚本会导致配置丢失，同时破坏了venv的独立性，不适合团队协作。
• 手动添加.pth文件：由于你已经安装了正式版本，Python会优先加载site-packages中已存在的my_module目录，.pth添加的路径优先级更低，因此无法覆盖正式版本。而开发模式会替换掉正式安装的包引用，确保开发代码优先加载。

替代方案：PYTHONPATH（适合临时场景） #

如果你只是临时需要加载src目录代码，不想用开发模式，也可以用direnv自动管理PYTHONPATH：

1. 在项目根目录创建.envrc文件：

echo 'export PYTHONPATH="$PYTHONPATH:$PWD/src"' >> .envrc

2. 允许direnv加载这个配置：

direnv allow

这样每次进入项目目录时，direnv会自动激活venv（如果配置了的话）并设置PYTHONPATH，无需手动输入命令。但这种方法不如开发模式规范，适合临时调试场景。

确认pyproject.toml配置正确性 #

确保你的pyproject.toml包含以下关键配置（hatchling作为构建后端）：

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my_module"
version = "0.1.0"

内容的提问来源于stack exchange，提问作者Peter V. Mørch