Python环境管理

写 LangGraph 之前，得先把 Python 环境搭好。这是新手最容易踩坑的环节——版本冲突、激活失败、装包慢、依赖一团乱，多半都源于环境管理没做对。本篇把主流方案讲透，并给出推荐组合。

一、为什么需要虚拟环境

Python 的包是全局安装的——如果你在 A 项目用 langgraph 0.2，在 B 项目用 langgraph 0.1，全局只有一个版本，必然冲突。

虚拟环境（Virtual Environment） 就是为每个项目建一个独立的 Python "小房间"，里面装自己的包版本，互不干扰。

系统 Python (全局)
├── venv-A  (langgraph 0.2 + langchain-openai 0.1)
├── venv-B  (langgraph 0.1 + langchain 0.0.300)
└── venv-C  (其它项目)

规则：每个项目一个虚拟环境，绝不全局装包。

二、主流工具对比

工具	来源	速度	依赖管理	多版本管理	推荐场景
venv	Python 内置	中	❌ 仅虚拟环境	❌ 需配合 pyenv	入门、临时项目
pip	Python 内置	中	❌ 需手动 requirements	❌	简单调包
uv	Astral (Rust)	🚀 极快	✅ 优秀	✅ 内建	强烈推荐
poetry	社区	慢	✅ 优秀 + 打包	❌	需要发布 PyPI 包
conda	Anaconda	慢	✅	✅	数据科学、非 Python 依赖
pyenv	社区	-	❌	✅ 仅版本管理	配合 venv 用

下面逐一演示。推荐方案：uv——速度快、能管依赖、能管版本，一个工具顶仨。

三、venv（Python 内置）

最朴素的方案，Python 自带，无需额外安装。

# 创建虚拟环境（在项目根目录执行）
# Windows / macOS / Linux 通用
python -m venv .venv

# 激活（注意 Windows 与 macOS/Linux 路径不同！）
# Windows (PowerShell)
.venv\Scripts\Activate.ps1
# Windows (CMD)
.venv\Scripts\activate.bat
# macOS / Linux
source .venv/bin/activate

# 激活后命令行前面会出现 (.venv) 标识
# 装包
pip install langgraph -i https://pypi.tuna.tsinghua.edu.cn/simple

# 退出虚拟环境
deactivate

导出依赖：

pip freeze > requirements.txt
# 别人拿到项目后
pip install -r requirements.txt

优点：零依赖、零学习成本。缺点：速度一般、不管多版本、不管 lockfile。

四、pip（包管理器）

pip 是 Python 标准包管理器，所有方案最终都会调到它。这里只讲两个高频用法：

# 装指定版本
pip install "langgraph>=0.2,<0.3"

# 卸载
pip uninstall langgraph

# 查看已装
pip list

pip 镜像源配置见后文「pip 镜像源」小节。

五、uv（强烈推荐）

uv 是 Astral 公司用 Rust 写的下一代 Python 工具，速度比 pip 快 10-100 倍，集成了版本管理 + 虚拟环境 + 依赖管理，一个工具替代 venv + pip + pip-tools + pyenv。

# 安装 uv
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS / Linux
curl -LsSf https://astral.sh/install.sh | sh

# 初始化项目（自动生成 pyproject.toml + .python-version + .venv）
uv init my-langgraph-project
cd my-langgraph-project

# 指定 Python 版本
uv python install 3.12
uv python pin 3.12

# 装包（自动创建/复用 .venv，自动写入 pyproject.toml）
uv add langgraph langchain-openai langchain-core python-dotenv
# 用国内源
uv add langgraph --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 同步依赖（别人拉项目后只需一句）
uv sync

# 运行脚本（自动用项目的 .venv）
uv run python test_env.py

为什么推荐 uv：

1. 极快：装几十个包几秒钟搞定。
2. 统一：一个工具管版本、环境、依赖，不用再装 pyenv + venv + poetry。
3. lockfile：自动生成 uv.lock，可复现安装。
4. 跨平台：Windows / macOS / Linux 一致。

对有 Java 背景的读者：uv 的 pyproject.toml + uv.lock 类似 Maven 的 pom.xml + 锁定版本，uv sync 类似 mvn install。

六、poetry

poetry 是社区流行的依赖管理 + 打包工具，适合需要发布到 PyPI 的库项目。

# 安装
# Windows / macOS / Linux 通用
pip install poetry -i https://pypi.tuna.tsinghua.edu.cn/simple

# 也可以用官方安装脚本
# macOS / Linux
curl -sSL https://install.python-poetry.org | python3 -

# 新建项目
poetry new my-project
cd my-project

# 添加依赖
poetry add langgraph langchain-openai

# 装好全部依赖
poetry install

# 运行
poetry run python main.py

优点：依赖管理成熟、poetry.lock 可复现、能打包发布。缺点：速度慢、对 Windows 支持偶尔抽风。对纯学习/应用项目，更推荐 uv。

七、conda

conda 适合数据科学场景，特别是需要非 Python 依赖（如 CUDA、特定库的二进制）时。

# 创建环境
conda create -n langgraph-env python=3.12

# 激活
conda activate langgraph-env
# Windows / macOS / Linux 命令一致

# 装包
conda install langgraph -c conda-forge
# 也可以用 pip 装不在 conda 源的包
pip install langchain-openai -i https://pypi.tuna.tsinghua.edu.cn/simple

# 退出
conda deactivate

缺点：体积大、慢。如果不需要非 Python 依赖，不推荐用 conda。

八、pyenv（多版本管理）

pyenv 只做一件事：在同一台机器上安装多个 Python 版本并切换。

# macOS / Linux 安装
curl https://pyenv.run | bash

# Windows 推荐用 pyenv-win
# PowerShell
Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"

# 安装某个 Python 版本
pyenv install 3.12.4

# 设置局部版本（在项目目录）
pyenv local 3.12.4   # 会生成 .python-version 文件

通常 pyenv 配合 venv 使用：pyenv 切版本，venv 建环境。但 uv 内建版本管理，一个顶俩。

九、.python-version 文件

很多工具（uv、pyenv、poetry）都认这个文件。文件里写一行版本号：

3.12

放在项目根目录，进入项目时工具会自动读取并切换到该版本。强烈建议每个项目根目录都放一个。

十、pip 镜像源配置

国内直连 PyPI 很慢，配置清华源加速。

Windows：在 %APPDATA%\pip\ 下建 pip.ini（路径：C:\Users\你的用户名\AppData\Roaming\pip\pip.ini）：

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

macOS / Linux：在 ~/.pip/ 或 ~/.config/pip/ 下建 pip.conf：

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

临时使用（不改全局）：

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

uv 的镜像源配置在 uv.toml 或环境变量：

# Windows PowerShell
$env:UV_INDEX_URL = "https://pypi.tuna.tsinghua.edu.cn/simple"
# macOS / Linux
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

十一、推荐方案

对学 LangGraph 的同学：

• 应用项目 / 学习：uv（一招走天下）
• 库开发：uv 或 poetry
• 数据科学：conda（仅在有非 Python 依赖时）

本教程后续假设你已用 uv 初始化好项目。

十二、常见踩坑

1. 多版本冲突：系统里装了多个 Python（Microsoft Store 版、官网版、Anaconda 版）。python -m venv 时一定要确认用的是哪个 python。Windows 用 where python，macOS/Linux 用 which python。
2. 激活失败（PowerShell 执行策略）：Windows 跑 .venv\Scripts\Activate.ps1 报"无法加载，未签名"。解决：

   Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

3. PATH 问题：装完 Python 命令行找不到 python 或 pip。Windows 安装时务必勾选 "Add Python to PATH"。
4. 激活了还是装到全局：注意看命令行前缀有没有 (.venv)，没激活就装包等于装到全局。
5. 包版本不一致：团队协作时 requirements.txt 不带 hash，别人装的版本可能和你不同。用 uv.lock 或 poetry.lock 才能保证完全一致。
6. 国内源证书报错：清华源偶尔证书校验失败，临时加 --trusted-host pypi.tuna.tsinghua.edu.cn。
7. Python 版本太老：LangGraph 0.2+ 要求 Python 3.9+，建议用 3.11 或 3.12。python --version 查一下。

十三、小结

• 每个项目一个虚拟环境，绝不全局装包。
• 主流方案对比：venv（内置）/ uv（推荐）/ poetry（库开发）/ conda（数据科学）。
• 推荐 uv：速度快、能管版本和依赖、跨平台一致。
• Windows 激活用 .venv\Scripts\Activate.ps1，macOS/Linux 用 source .venv/bin/activate。
• 配清华源加速，pip.ini / pip.conf 永久生效。
• 每个项目放一个 .python-version 文件。

环境管理就讲到这，下一篇正式搭建开发环境并安装 LangGraph 全套依赖。开发环境搭建 →