新项目Python版本选错了,库不支持,我踩了三个坑

上个月开始一个新项目，我直接装了Python 3.13，心想用最新版总没错。

结果第一周就撞墙：某个关键库报错"不支持Python 3.13"，issue里一堆人反馈，作者回复"等正式版再说"。

我被迫降级到3.12，然后又遇到第二个坑：虚拟环境管理混乱，依赖冲突。第三个坑更离谱：同一份代码，同事跑不起来。

这篇文章记录我踩的三个坑，以及背后的原因和解决方案。如果你正要开新项目，这篇文章能帮你省很多麻烦。

坑一：Python版本太新，库不支持

遇到什么问题

项目需要一个叫some-cryptic-lib的库（化名，真实情况类似）。我执行：

pip install some-cryptic-lib

报错：

ERROR: Package 'some-cryptic-lib' requires a different Python: 3.13.0 not in '>=3.8,<3.13'

去GitHub看issue，有人2025年6月就反馈了，作者回复："Python 3.13的free-threading改动太大，我们要测试完才支持。"

等了一个月，还是不行。

为什么会这样

Python 3.13改动很大：

1. Free-threading（自由线程）
   ：去掉了GIL，但很多C扩展库依赖GIL保证线程安全，需要重写
2. C API变更
   ：底层C接口改了，很多库要适配
3. 实验性功能
   ：JIT编译器、新的REPL，都可能影响兼容性

这些改动对库作者来说是负担，不是每个库都有精力第一时间适配。

怎么避免

经验法则：新项目选最新版本的上一个版本。

2026年4月，最新版是3.13，稳定版选3.12。

更保守一点：选3.11。3.11是公认最稳定的版本之一，几乎所有库都支持。

具体判断方法：

pip index versions some-cryptic-lib

如果requires Python >=3.8,<3.13，说明不支持3.13。

我的解决方案

降级到Python 3.12：

brew install python@3.12pyenv install 3.12.9pyenv global 3.12.9

坑二：虚拟环境管理混乱，依赖冲突

遇到什么问题

项目A用requests==2.28.0，项目B用requests==2.31.0。

我一开始直接在全局环境装包，结果：

pip install requests==2.28.0  # 项目Apip install requests==2.31.0  # 项目B，覆盖了A的版本

项目A跑不起来，报错API不兼容。

为什么会这样

Python的包是装在"site-packages"目录下的，全局共享。不同项目如果依赖不同版本的包，就会冲突。

这不是Python的问题，是使用方式的问题。

怎么避免：必须用虚拟环境

方法一：venv（Python自带，最轻量）

python -m venv myenvmyenv\Scripts\activatesource myenv/bin/activatepip install requests==2.28.0deactivate

每个项目一个虚拟环境，互不干扰。

方法二：Conda（适合数据科学项目）

conda create -n myproject python=3.12conda activate myprojectconda install requestsconda deactivate

Conda的优势是可以装非Python依赖（如CUDA），适合机器学习项目。

我的解决方案

项目结构改为：

project_a/├── venv/├── requirements.txt└── src/project_b/├── venv/├── requirements.txt└── src/

每个项目独立虚拟环境，依赖写在requirements.txt：

requests==2.28.0pandas==2.0.0numpy==1.24.0

一键安装：

pip install -r requirements.txt

坑三：同一份代码，同事跑不起来

遇到什么问题

我代码写好了，推到Git。同事拉下来，装依赖，报错：

ModuleNotFoundError: No module named 'some_package'

但我的机器上明明没问题。

为什么会这样

三个原因：

1. 依赖没写全
   ：我只装了自己需要的包，忘记记录依赖
2. 版本不锁定
   ：同事pip install时装了最新版，和我用的版本不一样
3. Python版本不同
   ：我用3.12，他用3.10，某些库API不同

怎么避免

第一步：正确生成requirements.txt

pip freeze > requirements.txt

这会记录所有包和精确版本：

requests==2.28.0urllib3==1.26.18certifi==2023.7.22...

第二步：锁定Python版本

项目根目录创建.python-version文件：

3.12.9

如果用pyenv，会自动读取这个文件。

第三步：明确依赖范围

只用核心依赖，不要把开发工具写进requirements.txt：

requests==2.28.0pandas==2.0.0pytest==7.4.0black==23.7.0mypy==1.5.0

我的解决方案

项目结构：

myproject/├── .python-version      # 锁定Python版本├── requirements.txt     # 生产依赖├── requirements-dev.txt # 开发依赖├── venv/└── src/

同事拿到项目后：

pyenv installpython -m venv venvsource venv/bin/activate  # Windows: venv\Scripts\activatepip install -r requirements.txtpython src/main.py

总结：新项目Python版本选择清单

我把这些坑总结成一个检查清单：

第一步：选Python版本

• 最新版是3.x，稳定版选3.(x-1)
• 2026年推荐：3.12（稳定）或3.11（更保守）
• 检查关键库是否支持：pip index versions 库名

第二步：创建虚拟环境

python -m venv venvsource venv/bin/activate  # Windows: venv\Scripts\activate

第三步：记录依赖

pip freeze > requirements.txt

第四步：锁定版本

• 创建.python-version文件
• 把venv/写进.gitignore

第五步：团队协作

• README写清楚环境配置步骤
• 提供一键脚本：

#!/bin/bashpython -m venv venvsource venv/bin/activatepip install -r requirements.txt

一个建议：pyenv管理多版本Python

如果你像我一样，要在多个项目间切换，不同项目用不同Python版本，强烈建议装pyenv。

curl https://pyenv.run | bashpyenv install 3.11.9pyenv install 3.12.9cd project_apyenv local 3.11.9  # 自动创建.python-version文件cd project_bpyenv local 3.12.9

每次进入项目目录，Python版本自动切换，不用手动改。

Windows用户可以用pyenv-win，原理一样。

最后说一句

新项目第一天，花10分钟把环境搭好，比后面踩一星期坑划算得多。

Python版本选稳定版，虚拟环境必须用，依赖一定要记录。

这三件事做到位，后面会顺很多。

别像我一样，新项目第一天就撞墙。