Python 知识系列（七）：虚拟环境与依赖管理

基础说明

为什么需要虚拟环境？

在Java世界里，Maven或Gradle会为每个项目管理一个明确的依赖树。不同的项目可以在 pom.xml 中依赖同一个库的不同版本（例如，Project A依赖log4j 1.2，Project B依赖log4j 2.17），构建工具会处理好这一切，不会互相干扰。

然而，Python的默认行为不同。当你执行 pip install <package> 时，它会默认将包安装到一个全局的 site-packages 目录中。（全局指的是当前操作系统下全局共享）

这会导致灾难性的问题：

• 版本冲突 (Dependency Hell): 假设你的AI应用A需要 tensorflow==2.10，而你另一个Web应用B需要 tensorflow==2.15。如果你在全局环境中安装，后安装的会覆盖前一个，导致其中一个应用无法正常工作。
• 环境污染: 全局环境会变得越来越臃肿，你甚至搞不清哪些包是哪个项目需要的。
• 不可复现性: 当你将代码分享给同事或部署到服务器时，你无法保证他们的环境和你本地的全局环境完全一致，导致”在我机器上能跑”的经典问题。

解决方案：虚拟环境 (Virtual Environment)

虚拟环境是一个自包含的目录，它里面有特定版本的Python解释器和一套独立的、与全局环境隔离的第三方库。

原生基础工具链：venv + pip + requirements.txt

这是Python官方内置的、最基础也是必须掌握的一套工具。

1. venv：创建和管理虚拟环境

1.1 创建虚拟环境

在你的项目根目录下，打开终端并执行：

# 'venv' 是模块名，第二个 'venv' 是你想创建的目录名，这是一种约定俗成的命名
python -m venv venv

执行后，项目下会多出一个 venv 目录。这个目录包含了Python解释器的副本和管理包的脚本。

最佳实践： 立即将 venv/ 添加到你的 .gitignore 文件中，因为环境是本地的，不应该提交到版本控制系统。

1.2 激活虚拟环境

激活后，你的终端提示符会发生变化，明确告诉你当前正处于哪个虚拟环境中。

在 macOS / Linux 上:

source venv/bin/activate
# (终端提示符前会出现 (venv))

1.3 停用虚拟环境

无论在哪个系统，只需在终端输入：

deactivate

2. pip：在虚拟环境中安装包

确保你的虚拟环境已激活！ 之后所有pip命令都将作用于这个独立的环境。

# 安装最新的 numpy
pip install numpy

# 安装特定版本的 langchain
pip install langchain==0.1.16

# 升级一个已安装的包
pip install --upgrade numpy

# 查看已安装的包
pip list

# 卸载一个包
pip uninstall numpy

3. requirements.txt：项目的依赖清单

当你为一个项目安装了所有必要的包之后，需要将这些依赖”冻结”下来，以便其他人或部署系统能够复现。

3.1 生成 requirements.txt 文件

在激活的虚拟环境中，执行：

pip freeze > requirements.txt

这会生成一个 requirements.txt 文件，内容类似：

langchain==0.1.16
langchain-community==0.0.34
numpy==1.26.4
... (所有依赖及其精确版本)

3.2 从 requirements.txt 安装依赖

当你的同事获取了你的项目代码后，他们只需创建并激活自己的虚拟环境，然后运行：

pip install -r requirements.txt

pip 会自动读取文件并安装所有指定版本的包，完美复现你的开发环境。

最佳实践：UV

1. 为啥用uv

uv 是一款一站式、超高速的 Python 工具，核心能做这几件事：

• 依赖管理：替代 pip/poetry，极速安装、更新、锁定项目依赖，生成规范的 pyproject.toml 和 uv.lock 文件；
• Python 版本管理：替代 pyenv，一键安装、切换不同 Python 版本，无需额外配置；
• 虚拟环境管理：替代 venv/conda（轻量场景），自动创建、激活项目专属虚拟环境，关联指定 Python 版本；
• 兼容传统生态：可导出 requirements.txt，适配 pip 等传统工具，兼顾新旧项目。

简单说，uv 把 “装 Python 版本 + 管虚拟环境 + 装依赖” 的多个工具功能整合，且速度比传统工具快 10-100 倍。

uv安装

uv官方最推荐的安装方式是使用curl 脚本，uv 本身是 Rust 编译的独立二进制，不依赖Python，最干净、最快，更新方便。

如果当前系统已经使用pipx安装了uv，可先进行卸载，否则忽略。

which uv
pipx list | grep uv    # 如果有内容，进行卸载
pipx uninstall uv      # uninstalled uv! ✨ 🌟 ✨
which uv               # uv not found

使用官方脚本安装uv

curl -LsSf https://astral.sh/uv/install.sh | env UV_NO_MODIFY_PATH=1 sh
uv --version    # uv 0.9.27 (b5797b2ab 2026-01-26)
# 如果安装完 uv 指令不能用，则尝试更新系统环境变量，或者重新安装

uv版本升级

uv self update

2. uvPyhton版本管理

# 查看已安装的 Python
uv python list

# 安装特定版本 Python
uv python install 3.12

# 移除 Python
uv python uninstall 3.12        # 删除所有 3.12.x 系列（通常 uv 会选最新 patch）
uv python uninstall 3.12.9      # 精确删除这个 patch 版本
uv python uninstall --all       # 删除所有 uv 管理的 Python

3. uv创建新项目

# 初始化一个普通项目
uv init project_a --python 3.12

# 项目布局
my_project/
├── pyproject.toml
├── uv.lock
├── .python-version
└── README.md

# 初始化一个库项目（src 布局）
uv init --lib project_a --python 3.12

# 项目布局
crawl4ai_wrapper/
├── src/
│   └── crawl4ai_wrapper/
│       └── __init__.py
├── pyproject.toml
├── uv.lock
└── README.md

【非必选】然后可以在pyproject.toml中加入项目必备依赖。

解析依赖（如果没虚拟环境，自动创建）

相当于pip install -r requirements.txt但更快（并发下载 + 安装）

uv sync

效果：

• 自动创建 .venv/
• 解析依赖 → 生成/更新 uv.lock
• 安装 lock 中依赖

如果是刚下载了一个其它uv相关，直接执行uv sync即可。

4. uv管理老pip + requirements.txt项目

cd old_pip_project

# 初始化项目
uv init    # 你会得到：pyproject.toml

# 如果项目需要制定版本 Python
uv init --python=3.11

# 导入 requirements.txt 到 uv; uv 会:
#   解析 requirements.txt
#   写入 pyproject.toml
#   生成 uv.lock
uv add -r requirements.txt

# 如果有 dev-requirements.txt 也一并导入
uv add -r requirements-dev.txt --dev

5. uv管poetry项目

uv天然兼容pyproject.toml，我们保留该文件，删除poetry痕迹即可。

poetry的pyproject.toml如下：

[tool.poetry]
name = "xxx"

[tool.poetry.dependencies]
python = "^3.11"
requests = "^2.31"

[tool.poetry.group.dev.dependencies]
pytest = "^8.0"

改成PEP 621标准（uv原生）

注意：该步骤可以省略，uv原生兼容poetry的pyproject.toml格式，但是不符合标准规范。

[project]
name = "xxx"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
  "requests>=2.31",
]

[project.optional-dependencies]
dev = [
  "pytest>=8.0",
]

然后删除poetry的lock文件

rm poetry.lock

用uv重新锁定

uv sync

6. 依赖管理

# 添加运行时依赖（会自动创建 .venv + 更新 uv.lock）
uv add fastapi uvicorn httpx

# 添加开发依赖（推荐写到 dev 组）
uv add --group dev ruff pytest pytest-cov pre-commit

# 同时添加多个
uv add pandas numpy "matplotlib>=3.9" --group dev

# 移除依赖
uv remove httpx
uv remove pytest --group dev

7. 日常使用

点击图片可查看完整电子表格

其它可选组合

Poetry

1. 为什么要用Poetry

传统方式中，requirements.txt 只记录了直接依赖，无法保证间接依赖的版本一致性，导致”在我的机器上能跑”的问题。Poetry方式，pyproject.toml 中声明依赖版本范围，更加灵活和清晰。

Poetry 的优势：

• 统一管理： 一个工具同时处理环境创建、依赖管理、打包和发布。
• 强大的依赖解析： 能解决复杂的依赖冲突，找到一个兼容所有包的版本组合。
• 确定性构建： 使用 poetry.lock 文件锁定每个依赖（包括子依赖）的精确版本，确保在任何地方安装的结果都完全一致。
• 项目标准化： 使用 pyproject.toml 文件管理项目元数据和依赖，这是Python官方推荐的标准。

2. Poetry的组成

2.1 pyproject.toml：单一配置文件

Poetry遵循 PEP 518 规范，使用 pyproject.toml 作为唯一的项目配置文件。

这个文件统一管理了项目元数据（名称、版本、作者等）、依赖项、开发依赖项、脚本以及构建系统配置。这极大地简化了项目结构，告别了分散的 setup.py, requirements.txt, MANIFEST.in 等文件。

2.2 poetry.lock：确定性构建

当添加或安装依赖时，Poetry会解析所有依赖（包括子依赖）的具体版本，并将其写入 poetry.lock 文件。 这个文件锁定了每个包的精确版本和哈希值，确保任何人在任何环境下使用 poetry install 命令时，都会安装完全相同的依赖组合，实现了真正的确定性构建和可复现性。

2.3 内置的虚拟环境管理

Poetry 会自动为项目创建和管理独立的虚拟环境，将项目依赖与全局Python环境或其他项目隔离开来，从根本上解决了版本冲突问题。无需再手动执行 python -m venv venv 或 virtualenv 命令。

2.4 一体化工作流

Poetry提供了一个覆盖项目生命周期的完整命令集，包括：new, init, install, update, add, remove, show, run, shell, build, publish 等。这意味着从项目创建到发布到PyPI（Python包索引），都可以在一个工具内完成，无需切换。

3. Poetry 使用

3.1 安装 pipx

# 用 --user 安装 pipx（会装到用户目录，不依赖当前 Python 版本的全局环境）
python -m pip install --user pipx
python -m pipx ensurepath

# pipx ensurepath 会自动在你的 shell 配置文件中添加 ~/.local/bin 到 PATH。
# 重启终端或执行
source ~/.zshrc  (或 ~/.bashrc)

# 验证pipx
pipx --version

3.2 安装 poetry

# pipx 安装 poetry
pipx install poetry

# 验证 poetry
which poetry    # which poetry 应该指向 ~/.local/bin/poetry
poetry --version

# 全局配置 peotry，让 poetry 在项目根目录创建虚拟环境，而不是集中管理：
poetry config virtualenvs.in-project true

3.3 为什么用pipx 安装poetry

pipx 就是为「工具类 Python 应用（尤其是命令行工具）」量身设计的，是安装这类工具的最优选择，没有之一。

4. peotry初始化新项目

poetry new my-awesome-project
cd my-awesome-project

目录结构如下：

my-awesome-project
├── pyproject.toml
├── README.md
├── my_awesome_project
│   └── __init__.py
└── tests
    └── __init__.py

5. peotry初始化现有项目

cd your-existing-project
poetry init

这个命令会引导您填写项目名称、版本、描述、作者、许可证等信息，最终生成 pyproject.toml 文件。

5.1 pyproject.toml 示例：

[tool.poetry]
name = "my-awesome-project"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]
readme = "README.md"
packages = [{include = "my_awesome_project"}]

[tool.poetry.dependencies]
python = "^3.8"  # 指定兼容的 Python 版本
requests = "^2.28.0"  # 添加一个生产依赖

[tool.poetry.group.dev.dependencies]  # 开发依赖组 (Poetry 1.2.0+)
pytest = "^7.0.0"
black = "^22.0.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

6. 虚拟环境

6.1 虚拟环境创建

当第一次运行 poetry install 时，Poetry 会自动检测并创建一个与项目隔离的虚拟环境，命名.venv。

poetry install

默认情况下，虚拟环境会创建在系统的一个缓存目录中（例如 ~/Library/Caches/pypoetry/virtualenvs on macOS）。之前我们通过全局配置poetry config virtualenvs.in-project true，已经让它在项目目录内创建虚拟环境了，便于IDE工具使用。

6.2 虚拟环境激活

使用source .venv/bin/activate 即可激活虚拟环境。

也可以使用 poetry env activate 命令，此命令会将激活虚拟环境的命令打印到控制台。

在 Poetry 2.0.0 版本前，使用：poetry shell 命令激活。

7. peotry依赖管理

7.1 添加依赖

# 添加一个生产依赖
poetry add requests

# 添加一个只在开发时使用的依赖 (如测试框架)
poetry add pytest --group dev

Poetry 会自动找到合适的版本，更新 pyproject.toml 和 poetry.lock。

可以通过以下指令查看依赖：

# 查看已安装的依赖树
poetry show --tree

# 查看过时的依赖
poetry show --outdated

7.2 安装全部依赖

当你初次拿到一个使用Poetry的项目时，只需运行：

poetry install

Poetry 会自动创建虚拟环境（通常在项目目录外的某个缓存目录中）并根据 poetry.lock 文件精确安装所有依赖。

注意： 如果原项目非Poetry项目，需要先安装requirements.txt 依赖！在执行install

poetry add --from requirements.txt
poetry install

7.3 更新依赖

更新所有依赖到最新兼容版本：

poetry update

更新特定依赖：

poetry update requests

注意： 升级依赖有风险，升级前推荐备份当前依赖配置和poetry.lock、pyproject.toml 文件。

# 导出当前依赖到 requirements.txt 备用
poetry export -f requirements.txt --output requirements.txt --without-hashes

# 提交 poetry.lock 到版本控制（Git）
git add poetry.lock pyproject.toml
git commit -m "backup: 升级依赖前的锁文件"

7.4 移除依赖

poetry remove requests

pyenv

pyenv 是一款跨平台的 Python 版本管理工具（独立于虚拟环境），核心作用是在单台机器上实现多个 Python 版本的 “无痛切换”，且不干扰系统自带的 Python。

1. 安装 pyenv

pyenv 做多Python版本管理，就是一台设备中可以安装Python 9、12、13等。

# 安装 pyenv + 虚拟环境插件
brew install pyenv pyenv-virtualenv

# 配置 pyenv 到你的 shell 配置文件 (~/.zshrc 或 ~/.bashrc)。
# pyenv configuration
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"  # 如果你计划使用 pyenv-virtualenv (推荐)

# 重启终端或执行
source ~/.zshrc (或 ~/.bashrc)。

2. pyenv简单使用

# 使用 pyenv 安装 Python 3.12.6 (或你偏好的最新稳定版)：
pyenv install 3.12.6

# 为项目设置Pyton版本：
cd you_project
pyenv local 3.12.6


python --version

# 移除当前项目设置的Python版本/虚拟环境
pyenv local --unset

3. pyenv + virtualenv

pyenv + virtualenv组合，可以将Python版本和虚拟环境都交由pyenv 管理。

# 创建并激活虚拟环境（如果当前系统中venv虚拟环境不存在可创建，该环境跨项目共享）
cd ~/you_project
pyenv virtualenv 3.12.0 venv

# 给当前项目目录设置专属的 Python 环境（版本 / 虚拟环境）
pyenv local venv

注意： 若当前项目为poetry 管理，最佳实践为pyenv 仅管理Python版本，poetry 管理虚拟环境和依赖。也就是poetry 项目不推荐使用virtualenv 。

Conda

1. 为什么要用Conda

个人痛点： 之前我用了pyenv，后面Python和项目环境多了后，发现环境冲突严重，管理混乱，难，所以来切换了Conda。

通用解答： 对于习惯了Maven或Gradle这类构建和依赖管理工具的Java工程师来说，Python世界的包管理似乎有些”混乱”。pip是Python官方的包安装器，但它在处理复杂的非Python依赖（如NVIDIA的CUDA、cuDNN，或底层的C++库）以及维护项目间环境隔离时，显得力不从心。

AI和数据科学项目恰恰严重依赖这类复杂的、非Python的底层库，并且不同项目（如一个基于TensorFlow 2.8，另一个基于PyTorch 2.0）可能需要不同版本甚至是冲突的依赖栈。

Conda正是为了解决这些痛点而生。 它是一个与语言无关的包和环境管理器。

它可以：

• 管理环境： 像创建虚拟机一样，轻松创建完全隔离的运行环境，每个环境可以有自己的Python解释器版本、第三方库，甚至JDK版本。
• 管理跨语言的包： 不仅能安装Python包，还能安装C/C++库、R包、Java运行时等任何软件。
• 处理复杂的二进制依赖： AI库通常是编译好的二进制文件，Conda能很好地处理这些二进制包及其复杂的依赖关系，避免了在本地编译的痛苦。

因此，掌握Conda是搭建稳定、可复现AI开发和生产环境的第一步，也是必备技能。

2. Conda安装和配置

2.1 Conda安装

对于初学者，推荐安装Miniconda。Anaconda是一个”全家桶”，预装了数百个科学计算包，体积较大。Miniconda则只包含Conda、Python及其核心依赖，非常轻量，你可以按需安装自己需要的包。

MacOS系统安装：https://www.anaconda.com/docs/getting-started/miniconda/install#macos-2

安装完成后，关闭并重新打开你的终端。你会发现命令行提示符前面多了一个(base)字样，这表示你正处于Conda的默认base环境中。

运行以下命令来验证安装：

conda --version

关闭Conda终端启动时自动激活base环境

conda config --set auto_activate_base false

【更新】目前更推荐Conda + uv ，推荐直接看下一章节

2.2 必备组件安装

设置pip，安装pipx 和poetry

# 激活 conda 的 base 环境（作为全局基础环境）
conda activate base

# 【忽略这条】重置 pip 软连接，此时 pip 命令全局可用
#ln -sf ~/miniconda3/bin/pip ~/.local/bin/pip
# ln -sf ~/miniconda3/bin/pip3 ~/.local/bin/pip3

在bash 虚拟环境激活状态继续安装pipx 和poetry

# 安装 pipx
pip install --user pipx

# 初始化 pipx 路径（修复 pipx 的解释器路径）
pipx ensurepath

# 验证 pipx 是否正常
pipx --version

# 安装 poetry
pipx install poetry

安装了poetry 后，想与conda 配合使用，禁用poetry 自动创建其专属虚拟环境，使用conda的虚拟环境。

poetry config virtualenvs.create false

# （可选）确认配置生效，输出 false 说明配置成功
poetry config --list | grep virtualenvs.create

3. 环境管理

这是Conda最核心、最强大的功能。

3.1 创建环境

创建一个名为mcp-server-adapter的环境，并指定使用Python 3.13。

# 语法: conda create --name <环境名> python=<python版本>
conda create -n mcp-server-adapter python=3.13

# 如果想删除环境，使用 conda remove
conda remove --n mcp-server-adapter --all

3.2 常用命令

# 查看所有环境，当前激活的环境会有一个*号标记。
conda env list

# 激活环境
conda activate mcp-server-adapter

# 退出激活环境
conda deactivate

# 删除环境
# 语法: conda remove --name <环境名> --all
conda remove -n ai_project_1 --all

4. 包管理

请确保你已经激活了目标环境 (conda activate <环境名>) 再进行包管理操作！

4.1 使用conda管理包

# 搜索包，想知道Conda仓库里有没有某个包（例如tensorflow），以及有哪些版本。
conda search tensorflow

# 安装单个包
conda install numpy

# 同时安装多个包
conda install pandas scikit-learn

# 安装指定版本的包
conda install numpy=1.26.0

# 删除包
conda remove numpy

# 更新单个包到最新兼容版本
conda update numpy

# 更新所有包
conda update --all

# !!! 注意：conda管理的包体系跟pip独立，上述命令无法更新pip安装的包

4.2 使用poetry管理包

以现存的一个项目mcp-server-adapter为例，目前激活了conda环境且cd 到项目目录中

conda activate mcp-server-adapter
cd ~/xxx/mcp-server-adapter

使用poetry安装依赖

# 初始化
poetry init

# 如果项目原生为poetry项目直接安装依赖
poetry install

# 如果项目有 requirements.txt 则使用下面命令从requirements.txt 安装
poetry add $(cat requirements.txt)

附录：常用Conda命令速查表

Conda + uv

uv与conda如何分工

5. uv与Conda虚拟环境

目前默认已经安装好了Conda，如果没安装参考6.2 Conda安装和配置 。

安装uv

pipx install uv
uv --version

uv绑定Python解释器

在与conda的分工中我们讲到，uv负责管理依赖，而依赖在虚拟环境中，那么它如何知道其要使用的虚拟环境在哪里呢？

当uv需要一个Python时，它按这个顺序尝试：

1. 已 pin 的 Python（uv python pin）
2. 项目已有 .venv
3. uv 自己管理的 Python（uv managed installs）
4. 系统 PATH 中 符合要求 的 Python
5. ❌ 找不到 → 自己装一个（读取pyproject.toml文件，使用最低可用版本）

所以在conda项目中，如果想让uv使用conda的虚拟环境，要明确告诉它：

# 确保已经激活conda虚拟环境
conda activate xxx

# uv python pin：uv 的核心指令，意为「锁定默认 Python 解释器」
# $(which python)：shell 命令替换，会先执行 which python 获取当前终端激活的 Python 路径，再把路径传给 uv python pin
uv python pin $(which python)
# 此时输出 conda 管理的 Python，例如：/Users/yi/miniconda3/envs/xxxx/bin/python
uv python pin

扩展：虚拟环境跟Python有啥关系？为啥uv绑定了Python就知道虚拟环境了？

在 Python 里，真正决定一切的只有一个东西：Python 解释器。
它是唯一能执行代码的实体，也决定了版本号、标准库和能加载哪些第三方包。

所谓"虚拟环境"（无论是 .venv 还是 conda 的 envs），本质上只是把一个
Python 解释器和一套独立的目录结构组织在一起，让这个解释器只看到属于自己的依赖。

一个虚拟环境大概的样子：
.venv/
├── bin/python      ← 解释器（通常是软链）
├── lib/python3.x/site-packages/    ← 一个目录，用来存放第三方库

包管理工具（pip、uv）并不真的操作"虚拟环境"，它们只是调用某个确定的
Python 解释器，再把依赖安装到这个解释器对应的 site-packages 里。

因此，选择虚拟环境的本质，其实是在选择使用哪个 Python 解释器；
一旦解释器明确，虚拟环境、依赖安装、工具行为都会自然收敛。

6. uv使用-新项目

确保已经激活Conda虚拟环境，且到了特定项目目录

cd project-a
conda activate xxx

使用uv初始化项目，并绑定python

uv init
uv python pin $(which python)

执行完 uv init，会生成git相关、README.md、pyproject.toml等

# 目录结构如下
project/
├── pyproject.toml
├── README.md
├── .git
├── .gitignore
└── main.py

！！关于 --lib 参数，告诉 uv：这是一个”给别人 import 的库”，不是一个只跑脚本的项目

uv init --lib

# 目录结构如下
project/
├── pyproject.toml
├── README.md
├── .git
├── .gitignore
└── src/
    └── project_name/
        └── __init__.py

使用uv安装依赖

# 安装依赖并将依赖写入 pyproject.toml
uv add xxx

# 安装依赖，不写入 pyproject.toml
uv pip install xxx