Python 虚拟环境管理[学习笔记分享]
python 虚拟环境管理
参考文献
【uv】Python迄今最好的项目管理+环境管理工具（吧？）
GPT-5
DeepSeek-V3.1
在开发不同 python 项目时，所用到的 python 版本、package 都有可能不同
在命令行直接使用
python main.py，使用是全局环境
在相同环境下开发不同项目，不仅会污染全局环境，还可能因为缺失 module、版本冲突导致程序运行失败。这时，为不同的项目单独设立一个虚拟环境可以解决这些问题
虚拟环境
虚拟环境：你肯定用过，但不一定了解.hucci 认为虚拟环境包含三个主要内容——python 解释器、激活脚本、第三方包
（在 windows 环境中）先使用 python 的内置模块 venv（python 3.3+ 自带）在当前的根目录创建一个虚拟环境
python -m venv hello_env
执行后，会在根目录生成一个名为 hello_env 的文件夹。推荐取名为 .venv，因为当前主流编辑器都会自动识别该目录为虚拟环境。该文件夹下有四个文件（夹）
// windows 环境
Include
Lib
Scripts // 该目录下的 activate 为激活脚本
pyvenv.cfg
使用如下指令启动激活脚本，动态修改当前终端会话的环境变量，使系统优先使用虚拟环境中的 Python 解释器和第三方包。这时命令提示符前会出现虚拟环境的名称 hgello_env
PS D:\code\venv> hello_env\Scripts\activate
(hello_env) PS D:\code\venv>
第三方包则存放在 .\lib\site-packages 下，这时使用 pip install 引入的包也存放在该目录下
venv和pip的关系
venv 负责环境隔离
pip 负责包管理，在当前激活的环境中安装、卸载、升级 Python 包
常见环境管理工具
venv：python 官方提供的环境管理工具。venv 即 virtual environment 的简写
conda：第三方工具，配置文件、软件仓库均与 python 官方不同。且除 python 外，conda 还支持 C++、rust 等其他语言，是一个跨平台的包管理工具和环境管理工具
全局环境使用规范
GPT-5 认为，对于全局环境，有一些最佳实践和使用规范：
- 避免直接使用全局环境运行项目
- 保持全局环境简洁，只安装一些工具包（例如，
pip，pytest，black等开发工具） - 更新全局环境中的 Python 和工具
依赖管理
创建虚拟环境后，我们也需要把这些配置分享给其他开发者。这就是依赖管理的任务所在
pip freeze
早期，通常使用 pip freeze 命令来输出当前环境（如下为 hello_env 环境）下的依赖
(hello_env) PS D:\code\venv> pip freeze
numpy==2.3.3
pandas==2.3.2
python-dateutil==2.9.0.post0
pytz==2025.2
six==1.17.0
tzdata==2025.2
通常使用 pip freeze > requirements.txt 重定向输出为 requirements.txt。这样，别的开发者只需要 pip install -r requirements.txt 就可以一键安装
pyproject.toml
pip freeze 方法存在问题，它无法分别直接依赖和间接依赖。在卸载时不会同时卸载间接依赖，这样会留下一堆无用的孤儿依赖
包存在直接依赖和间接依赖的关系。如
pandas是用户pip install pandas直接引入的，而pytz是pandas的依赖，所以被自动安装
为了解决间接依赖问题，python 官方提出了统一的规范 pyproject.toml 文件。它允许开发者只记录直接依赖即可
[project]
name = "proj"
version = "0.1.0"
dependencies = [
"numpy==2.3.3",
"pandas==2.3.2"
]
python 官方并没有提供自动化工具来管理 pyproject.toml，也就是说 pyproject.toml 需要开发者手动填入直接依赖。不过社区提供了多种解决方案，如 poetry、uv、PDM
后面介绍 uv 的用法
uv
uv 是 Python 项目管理工具和环境管理工具，不仅提供了虚拟环境和包的管理功能，还可以快速搭建 python 项目的文件结构
安装 uv
官方文档指出，可以通过 powershell 命令一键安装 uv
PS D:\code\venv> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Downloading uv 0.8.22 (x86_64-pc-windows-msvc)
Installing to C:\Users\UnGoose\.local\bin
uv.exe
uvx.exe
uvw.exe
everything's installed!
To add C:\Users\UnGoose\.local\bin to your PATH, either restart your shell or run:
set Path=C:\Users\UnGoose\.local\bin;%Path% (cmd)
$env:Path = "C:\Users\UnGoose\.local\bin;$env:Path" (powershell)
它会自动安装并修改环境变量 PATH
创建项目
一般来说，创建项目同时需要新建 git 仓库、README.md 等内容
uv 提供 init 方法，可以快速完成这些任务
uv init <project_name> # 新建工作目录
uv init # 在当前目录建立项目结构
uv init 将会在目录中自动创建以下文件
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml
下一步，创建虚拟环境并激活，第三个参数代表虚拟环境相关的配置文件所在目录名，常使用 .venv
PS D:\code\hello_uv> uv venv .venv
Using CPython 3.11.7 interpreter at: C:\Users\UnGoose\anaconda3\python3.exe
Creating virtual environment at: .venv
Activate with: .venv\Scripts\activate
PS D:\code\hello_uv>.venv\Scripts\activate
(.venv) PS D:\code\hello_uv>
项目文件
此外，在第一次运行项目命令（例如 uv run、uv sync 或 uv lock）时，uv 还将在项目的根目录中创建一个虚拟环境和 uv.lock 等文件。因此 uv 的完整文件目录如下：
.
├── .venv
│ ├── bin
│ ├── lib
│ └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock
pyproject.toml 包含有关项目的元数据
.python-version 文件包含项目的默认 Python 版本。此文件告诉 uv 在创建项目的虚拟环境时使用哪个 Python 版本
.venv 文件夹包含您项目的虚拟环境，这是一个与系统其余部分隔离的 Python 环境。 这也是 uv 安装项目依赖项的地方
uv.lock 是一个跨平台锁定文件，其中包含有关项目依赖项的精确信息。此文件推荐纳入版本控制。该文件推荐由 uv 管理，不应手动编辑
依赖管理
使用 uv add 将依赖项添加到 pyproject.toml，这也会更新锁定文件和项目环境
uv add requests
使用 -r 参数可以从 requirements.txt 文件中一键添加依赖
uv add -r requirements.txt
使用 uv remove 可以删除依赖项
uv remove requests
需要导入虚拟环境时，也只需要 pyproject.toml 文件，并执行：
uv sync
以上命令会根据 pyproject.toml 自动创建或更新虚拟环境，方便快捷
运行命令
uv run 可以项目环境中运行任意脚本或命令
uv run main.py
直接用
python main.py运行的是当前命令行上下文里的 python，如果激活虚拟环境则运行虚拟环境的 python.exe
uv run main.py会自动挑选并加载合适的项目环境。且在每次uv run调用之前，uv 都会验证锁定文件是否与pyproject.toml最新，以及环境是否与锁定文件最新，从而使您的项目保持同步，而无需手动干预。uv run保证您的命令在一致的锁定环境中运行
临时运行脚本
当你需要临时运行一个带有第三方库的 python 脚本时，uv 也提供了解决方案
uv init --script main.py
uv run main.py
uv init --script 会识别 main.py 中的依赖，并在文件开头添加特定的字段。uv run 可以识别这些字段，临时安装第三方库执行
浙公网安备 33010602011771号