Python 环境管理入门：venv、pip 与依赖锁定实战

Python 装好就能写代码，但真正开始做项目时，第一个让人头疼的问题往往不是语法，而是环境：A 项目要 Django 4，B 项目要 Django 5；一台机器上装的包越来越多，最后连哪个项目用了哪个版本都说不清。这篇文章把 Python 环境管理最核心的三件套讲清楚：虚拟环境 venv、包管理器 pip、依赖锁定 requirements.txt，帮你从一开始就养成干净、可复现的项目习惯。

一、为什么需要虚拟环境

Python 的包是装在解释器层面的：如果所有项目共用同一套全局包，不同项目对同一个包的不同版本要求就会直接冲突。更麻烦的是，升级一个项目的依赖可能悄悄破坏另一个项目。

虚拟环境（virtual environment）就是给每个项目单独准备的一套 Python 解释器和包目录：项目 A 的包只装在项目 A 的环境里，项目 B 互不影响；删掉环境目录，项目依赖就干净地清掉了，不会污染系统 Python。

标准库自带的 venv 就够用，不需要一开始就上更重的工具。先学会 venv，再根据需要了解 conda、Poetry、uv 这些工具，会事半功倍。

二、用 venv 创建并激活环境

1. 创建环境

在项目目录下执行：

cd my-project
python3 -m venv .venv

这会在项目里生成一个 .venv 目录，里面是一份独立的解释器和 pip。目录名习惯用 .venv 或 venv，并记得把它加进 .gitignore，不要把几百兆的环境目录提交进代码仓库。

2. 激活环境

激活之后，终端里的 python 和 pip 都会指向这个环境，而不是系统全局：

# Linux / macOS
source .venv/bin/activate
# Windows（PowerShell）
.venv\Scripts\Activate.ps1

激活成功后，命令行提示符前面通常会出现 (.venv) 标记。退出环境用 deactivate 命令。养成习惯：进项目先激活，再装包、再运行，否则包很可能装错了地方。

一个常见坑是：在 IDE 里打开项目，却没有把解释器切换到 .venv 下的 Python，导致代码运行时找不到刚装好的包。解决办法是在 IDE 的解释器设置里手动选到 .venv/bin/python，而不是用系统默认解释器。

三、pip 的日常用法

pip 是 Python 的包安装工具，日常高频命令就这几个：

pip install requests            # 安装一个包
pip install requests==2.31.0     # 安装指定版本
pip install -U requests         # 升级到最新版
pip uninstall requests          # 卸载
pip list                        # 列出已安装的包
pip show requests               # 查看某个包的版本、位置、依赖

版本号怎么写才稳妥

写依赖时尽量写明版本范围，而不是裸写包名。裸写 requests 今天装的是 2.31，明年重装可能就是 2.32，行为变了都不知道问题出在哪。常见写法：

• requests==2.31.0：精确锁定，最稳妥，适合锁定文件。
• requests>=2.31,<3：允许小版本升级、不跨大版本，适合写在项目依赖声明里。
• requests~=2.31.0：兼容写法，允许 2.31.x 的补丁升级，不升到 2.32。

换源：下载慢时的正解

默认源在境外网络下可能很慢，可以临时指定国内镜像源，例如：

pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple

也可以把镜像写进 pip 配置文件（Linux/macOS 在 ~/.pip/pip.conf，Windows 在 %APPDATA%\pip\pip.ini），一劳永逸：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

注意：换源只是换下载地址，不改变包本身；生产环境或对供应链有要求的场景，要确认源的可信度。

四、依赖锁定：让别人的机器跑出同一套环境

只写代码不够，还要让别人（包括三个月后的自己）能一键复现你的环境。标准做法分两步：

1. 冻结当前环境

pip freeze > requirements.txt

pip freeze 会把当前环境里所有包连同精确版本列出来。别人拿到项目后执行：

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

就能得到基本一致的环境。

2. 区分开发依赖和生产依赖

pip freeze 有个缺点：它会把所有包一股脑列出来，包括你装着玩的工具。更干净的做法是手动维护两份文件：

• requirements.txt：项目运行时真正需要的包。
• requirements-dev.txt：只开发时用的工具，例如测试框架 pytest、代码格式化 black，文件里第一行写 -r requirements.txt 再列开发工具。

这样部署生产环境时只装 requirements.txt，镜像更小、攻击面也更小。

五、一套推荐的项目起手流程

新开一个 Python 项目时，按这个顺序走一遍，基本不会踩环境坑：

1. 新建项目目录，进目录。
2. python3 -m venv .venv 创建虚拟环境并激活。
3. 先升级环境里的 pip 本身：pip install -U pip。
4. 按需 pip install 项目依赖，跑通最小可运行版本。
5. 手动整理 requirements.txt，只写项目真正依赖的包和版本范围。
6. 提交代码前检查 .gitignore 是否排除了 .venv/ 和 __pycache__/。

六、常见问题速查

• 装了包却 import 报错：先确认当前终端是否激活了正确的虚拟环境，再确认 IDE 解释器是不是 .venv 下的那一个；用 which python（Windows 用 where python）看当前 python 的实际路径。
• pip 安装时报权限错误：不要用 sudo pip install 往系统 Python 里装包，那会污染系统环境；正确做法是回到虚拟环境里安装。
• 两个项目版本冲突：不要试图在一个环境里迁就两个版本，给每个项目各建一个 venv，这是虚拟环境存在的意义。
• requirements.txt 装不上：先看报错的第一个包，往往是某个包的新版本不再支持你用的 Python 版本；把该包版本放宽或升级 Python，再重新锁定。

环境管理没有花哨的技巧，核心就是一句话：每个项目一个独立环境，依赖写清楚版本，复现步骤写进项目里。把这套流程养成习惯，以后无论是换电脑、交接项目，还是部署到服务器，都会省下大量“在我机器上明明能跑”的排查时间。