自定义Python模块：pip/setup.py安装与PYTHONPATH配置的差异

核心差异对比 #

1. 安装与管理方式 #

• pip + setup.py：
  • 会将模块复制到Python环境的site-packages目录，成为环境的一部分，和其他第三方包一样被pip统一管理。你可以用pip list查看它，用pip uninstall卸载，还能通过pip freeze把它写入requirements.txt，方便在其他环境一键复刻。
  • setup.py里可以定义依赖、版本号、入口脚本、数据文件等，pip安装时会自动处理依赖安装，确保模块运行所需的其他包也被正确配置。
• PYTHONPATH配置：
  • 只是让Python解释器临时或永久识别模块所在的路径，模块本身仍留在原位置，不会被复制到site-packages。
  • 完全依赖手动维护路径，一旦模块移动位置，PYTHONPATH就得跟着修改；而且无法自动处理依赖，所有依赖包都得自己手动安装。

2. 生产环境适配性 #

• pip + setup.py：
  • 符合Python包管理的标准流程，不管是用Docker镜像打包、CI/CD自动化部署，还是在不同服务器搭建环境，都能通过pip install（甚至可以把模块打包成wheel或tar.gz文件）快速部署，环境一致性有保障。
  • 版本管理更清晰，setup.py里的版本号可以和代码版本绑定，方便追踪问题、回滚版本。
• PYTHONPATH配置：
  • 生产环境中极易出问题：比如不同用户的环境变量配置不一致，或者部署脚本遗漏PYTHONPATH设置导致模块找不到；多人协作时，每个人都得自己配置路径，容易出现本地运行正常但生产环境报错的情况。
  • 无法通过标准包管理工具追踪模块版本，排查问题时很难确定当前使用的是哪个版本的模块。

3. 被PYTHONPATH跳过的关键操作 #

手动配置PYTHONPATH确实会缺失pip安装时的核心后台操作：

• 依赖自动安装：pip会读取setup.py里的install_requires，自动下载安装所有依赖包，PYTHONPATH完全做不到这一点。
• 包元数据注册：pip会把模块的元数据（版本、作者、依赖等）写入环境的包索引，这样其他工具（比如pip check、IDE的代码提示）能识别到这个包；而PYTHONPATH添加的模块没有这些元数据，IDE可能无法正确识别，也无法用pip工具检查依赖是否缺失。
• 脚本与资源文件安装：如果setup.py里定义了entry_points（比如命令行脚本）或者package_data（需要打包的数据文件），pip会自动把脚本添加到环境的bin目录，把数据文件复制到对应位置；PYTHONPATH方式下这些资源无法被正确加载，脚本也不能直接全局调用。
• 编译扩展处理：如果模块包含C扩展或者需要编译的部分，pip安装时会自动编译适配当前环境的版本；PYTHONPATH方式下你得自己手动编译，否则可能出现兼容性问题。

总结 #

如果是要部署到生产环境的模块，优先选择pip + setup.py的方案，它能保证环境一致性、依赖管理清晰、部署流程标准化，避免PYTHONPATH带来的各种维护隐患。只有在本地临时调试模块、不想污染全局环境的情况下，才适合临时设置PYTHONPATH（比如用export PYTHONPATH=/path/to/module临时生效）。

内容的提问来源于stack exchange，提问作者Salvatore