Python 虚拟环境

1. 什么是 Python 虚拟环境

Python 虚拟环境可以理解为：

给每个 Python 项目准备一套独立的运行环境

它可以让不同项目拥有各自独立的：

Python 版本
第三方库
依赖版本

例如：

project-a
└── requests 2.x

project-b
└── requests 3.x

两个项目之间互不影响。

---

2. 为什么需要虚拟环境

假设电脑上只有一个全局 Python 环境。

项目 A 需要：

Django 4

项目 B 需要：

Django 5

如果都安装到全局 Python：

pip install django

就很容易出现版本冲突。

使用虚拟环境后：

project-a
└── .venv
    └── Django 4

project-b
└── .venv
    └── Django 5

每个项目维护自己的依赖。

这也是现在 Python 项目开发中非常常见的做法。

---

3. 不推荐把所有库装到全局环境

例如：

pip install requests
pip install numpy
pip install django
pip install flask

如果这些包全部安装到系统 Python 中，时间久了容易出现：

依赖混乱
版本冲突
不知道某个包属于哪个项目
环境难以复现

更推荐：

一个项目
一个虚拟环境

---

4. Python 自带的 venv

Python 自带：

venv

模块，可以创建虚拟环境。

首先查看 Python：

python --version

或者：

python3 --version

例如：

Python 3.13.5

---

5. 创建虚拟环境

进入项目目录：

cd project

创建虚拟环境：

python -m venv .venv

如果系统使用：

python3

则：

python3 -m venv .venv

这里：

.venv

是虚拟环境目录名称。

一般推荐使用：

.venv

---

6. 创建后的目录

例如项目：

project/

执行：

python -m venv .venv

之后：

project/
├── .venv/
└── main.py

虚拟环境中的 Python、pip 和安装的第三方库都会放在：

.venv

里面。

---

7. 为什么叫 .venv

名字不是固定的。

下面这些都可以：

python -m venv venv
python -m venv env
python -m venv .venv

但是现代 Python 项目里非常常见：

.venv

优点是：

名称统一
以 . 开头，不容易干扰项目目录
编辑器容易自动识别

---

8. 激活虚拟环境

创建虚拟环境后，一般需要激活。

Linux / macOS

source .venv/bin/activate

激活之后，终端前面通常会出现：

(.venv)

例如：

(.venv) moonlit@linux project $

表示当前正在使用：

.venv

虚拟环境。

---

9. Windows 激活

如果使用 Windows CMD：

.venv\Scripts\activate

PowerShell：

.venv\Scripts\Activate.ps1

Linux 和 macOS 通常使用：

source .venv/bin/activate

---

10. 激活后发生了什么

激活虚拟环境后执行：

which python

可能输出：

/home/moonlit/project/.venv/bin/python

说明现在执行：

python

实际使用的是：

项目里的 Python

而不是系统 Python。

---

11. 查看 Python 位置

Linux/macOS：

which python

例如虚拟环境没有激活时：

/usr/bin/python

或者：

/opt/homebrew/bin/python3

激活后：

/home/moonlit/project/.venv/bin/python

这样就可以确认当前到底使用的是哪一个 Python。

---

12. 查看 pip 位置

同样可以：

which pip

激活虚拟环境之后可能得到：

/home/moonlit/project/.venv/bin/pip

也就是说：

pip install requests

会把：

requests

安装到当前虚拟环境中。

---

13. 安装第三方包

虚拟环境激活之后：

pip install requests

这个包会安装到：

.venv

而不是全局环境。

查看：

pip list

例如：

Package    Version
---------- -------
pip        25.2
requests   2.32.5

---

14. 推荐使用 python -m pip

除了：

pip install requests

还可以：

python -m pip install requests

这种写法的好处是可以明确：

使用当前这个 Python 对应的 pip

例如：

python -m pip install requests

通常比单独写：

pip install requests

更不容易出现 Python 和 pip 对不上的问题。

---

15. 退出虚拟环境

退出虚拟环境：

deactivate

终端前面的：

(.venv)

就会消失。

例如：

(.venv) project $

执行：

deactivate

恢复：

project $

---

16. 虚拟环境不是每次都要重新创建

第一次创建：

python -m venv .venv

以后重新打开终端时，不需要再次：

python -m venv .venv

只需要重新激活：

source .venv/bin/activate

也就是：

创建：通常只需要一次
激活：每次新开终端通常需要重新执行

---

17. 删除虚拟环境

虚拟环境本质上就是一个目录。

如果不需要：

rm -rf .venv

即可删除。

以后需要时重新：

python -m venv .venv

然后重新安装依赖即可。

因此：

.venv

通常不属于需要永久保存的重要项目文件。

---

18. .venv 不应该提交到 Git

Python 虚拟环境可能非常大，而且里面有很多：

可执行文件
第三方包
缓存
平台相关文件

因此通常不会提交到 Git。

在：

.gitignore

中加入：

.venv/

例如：

project/
├── .gitignore
├── .venv/
├── main.py
└── requirements.txt

.gitignore：

.venv/

---

19. 那项目依赖怎么保存

虽然：

.venv

不提交 Git，

但是项目需要记录：

安装了哪些第三方库

传统方式通常使用：

requirements.txt

---

20. requirements.txt

查看当前环境中的包：

pip freeze

例如：

requests==2.32.5
urllib3==2.5.0

保存到文件：

pip freeze > requirements.txt

于是项目：

project/
├── .venv/
├── main.py
└── requirements.txt

---

21. 根据依赖文件恢复环境

别人拿到项目后，可以创建新的虚拟环境：

python -m venv .venv

激活：

source .venv/bin/activate

然后：

pip install -r requirements.txt

即可安装项目依赖。

所以一般：

.venv             不提交
requirements.txt  提交

---

22. 一个完整的 venv 工作流程

创建项目：

mkdir python-demo
cd python-demo

创建虚拟环境：

python -m venv .venv

激活：

source .venv/bin/activate

安装依赖：

python -m pip install requests

查看：

pip list

创建：

main.py

写入：

import requests

print(requests.__version__)

运行：

python main.py

保存依赖：

pip freeze > requirements.txt

退出：

deactivate

这就是最基础的 Python 虚拟环境流程。

---

uv 虚拟环境

23. 什么是 uv

除了 Python 自带的：

venv + pip

现在也可以使用：

uv

管理 Python 项目。

uv 可以处理：

Python 版本
虚拟环境
依赖安装
项目依赖
命令运行

对于新项目来说非常方便。

---

24. 安装 uv

如果在 macOS 使用 Homebrew：

brew install uv

查看版本：

uv --version

---

25. 使用 uv 初始化项目

创建目录：

mkdir python-demo
cd python-demo

初始化：

uv init

通常会生成类似：

python-demo/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

其中：

pyproject.toml

用于保存项目配置和依赖信息。

---

26. 使用 uv 创建虚拟环境

可以直接：

uv venv

默认通常会创建：

.venv

目录。

例如：

project/
├── .venv/
├── main.py
└── pyproject.toml

---

27. 指定 Python 版本

例如：

uv venv --python 3.13

表示使用：

Python 3.13

创建虚拟环境。

也可以使用 uv 管理 Python：

uv python install 3.13

然后：

uv venv --python 3.13

---

28. 激活 uv 创建的环境

uv 创建出来的：

.venv

本质上仍然是标准 Python 虚拟环境。

因此 Linux/macOS 一样可以：

source .venv/bin/activate

然后：

python --version

查看当前 Python。

---

29. uv add

如果是一个 uv 项目，推荐使用：

uv add requests

而不是：

pip install requests

uv add 不只是安装依赖，还会把依赖记录到：

pyproject.toml

中。

例如：

uv add requests

之后可能看到：

[project]
dependencies = [
    "requests>=2.32.5",
]

---

30. uv add 和 pip install

两者虽然都可以安装包，但作用不完全一样。

pip install

pip install requests

主要作用：

把 requests 安装到当前 Python 环境

uv add

uv add requests

主要作用：

安装 requests
+
把 requests 记录为项目依赖
+
更新锁文件

因此使用 uv 管理项目时，更推荐：

uv add

---

31. pyproject.toml

现代 Python 项目经常使用：

pyproject.toml

记录项目配置。

例如：

[project]
name = "python-demo"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
    "requests>=2.32.5",
]

这里可以看到：

项目名称
版本
Python 版本要求
项目依赖

---

32. uv.lock

使用 uv 添加依赖后，通常还会生成：

uv.lock

例如：

project/
├── .venv/
├── main.py
├── pyproject.toml
└── uv.lock

它用于锁定项目实际使用的依赖版本。

通常：

pyproject.toml
uv.lock

都应该提交到 Git。

而：

.venv

不提交。

---

33. uv run

uv 可以直接使用：

uv run python main.py

运行程序。

例如：

import requests

print(requests.__version__)

运行：

uv run python main.py

uv 会自动使用当前项目环境。

因此很多时候甚至不需要手动：

source .venv/bin/activate

---

34. 激活和 uv run 的区别

传统方式：

source .venv/bin/activate
python main.py

uv 方式：

uv run python main.py

两种方式都可以。

简单理解：

activate
让当前整个终端进入虚拟环境

而：

uv run
只让这一条命令在项目环境中运行

---

35. 使用 uv 安装开发工具

例如安装：

black

作为开发依赖：

uv add --dev black

然后运行：

uv run black .

这种方式可以确保项目使用固定版本的：

black

而不需要全局安装。

---

36. 同步项目环境

如果：

pyproject.toml
uv.lock

已经存在，

可以执行：

uv sync

uv 会根据项目依赖创建或更新：

.venv

这在：

git clone

一个项目之后非常常用。

---

37. uv 项目的常见流程

初始化：

uv init

添加依赖：

uv add requests

添加开发依赖：

uv add --dev black

运行：

uv run python main.py

格式化：

uv run black .

同步环境：

uv sync

这几个命令已经能够覆盖很多日常需求。

---

38. 克隆一个 uv 项目之后

假设：

git clone https://example.com/project.git
cd project

项目里有：

pyproject.toml
uv.lock

通常只需要：

uv sync

然后：

uv run python main.py

即可运行。

不需要把原作者的：

.venv

复制过来。

---

39. VS Code 与虚拟环境

在 VS Code 中，通常需要选择正确的 Python 解释器。

打开命令面板：

Command Palette

搜索：

Python: Select Interpreter

选择项目中的：

.venv/bin/python

这样：

运行
补全
类型检查
第三方库识别

都会使用当前项目环境。

---

40. Neovim 与虚拟环境

如果在终端中：

source .venv/bin/activate

然后启动：

nvim

很多 Python 工具会自动继承当前 Shell 环境。

也可以直接：

uv run python main.py

运行程序。

虚拟环境和编辑器是两个概念：

虚拟环境
负责 Python 和项目依赖

Neovim / VS Code
负责编辑代码

---

41. 常见问题：为什么 import 报错

例如：

import requests

编辑器提示：

Import "requests" could not be resolved

但明明执行过：

pip install requests

很可能是：

安装 requests 的 Python

和：

编辑器当前使用的 Python

不是同一个。

可以检查：

which python

以及：

python -m pip show requests

确认是否安装到了当前环境。

---

42. python、python3 和 .venv/bin/python

Linux/macOS 上可能同时存在：

python
python3

而虚拟环境中又有：

.venv/bin/python
.venv/bin/python3

激活虚拟环境之后：

which python

如果得到：

项目/.venv/bin/python

就说明当前：

python

已经指向虚拟环境。

因此激活后通常直接：

python main.py

即可。

---

43. 不要修改 .venv 里的文件

一般不要手动编辑：

.venv/

里面的内容。

例如：

.venv/bin
.venv/lib

这些应该由：

Python
pip
uv

自动管理。

如果虚拟环境出现严重问题，通常最简单的方式是：

rm -rf .venv

然后重新创建。

---

44. 每个项目一个 .venv

推荐：

projects/
├── web-project/
│   ├── .venv/
│   └── ...
│
├── data-project/
│   ├── .venv/
│   └── ...
│
└── python-demo/
    ├── .venv/
    └── ...

而不是所有项目共同使用：

一个巨大的全局 Python 环境

这样管理起来更加清晰。

---

45. venv 和 uv 怎么选

如果只是学习虚拟环境原理：

venv + pip

非常值得掌握，因为它属于 Python 的基础能力。

基本命令：

python -m venv .venv
source .venv/bin/activate
python -m pip install requests
deactivate

如果日常自己创建现代 Python 项目：

uv

会更加方便。

常见流程：

uv init
uv add requests
uv run python main.py

两者并不冲突。

理解：

venv

之后再使用：

uv

会更容易理解 uv 到底帮你做了什么。

---

46. venv 工作流速查

创建

python -m venv .venv

激活

source .venv/bin/activate

安装依赖

python -m pip install requests

查看依赖

pip list

导出依赖

pip freeze > requirements.txt

安装依赖

pip install -r requirements.txt

退出

deactivate

---

47. uv 工作流速查

初始化项目

uv init

创建虚拟环境

uv venv

添加依赖

uv add requests

添加开发依赖

uv add --dev black

运行程序

uv run python main.py

同步环境

uv sync

指定 Python

uv venv --python 3.13

---

48. 项目目录示例

使用 uv 的 Python 项目通常可以类似：

python-demo/
├── .venv/
├── .gitignore
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

其中：

.venv/

本地虚拟环境，不提交 Git。

pyproject.toml

项目配置和依赖声明。

uv.lock

锁定依赖版本。

.python-version

记录项目使用的 Python 版本。

---

小结

Python 虚拟环境最核心的目的就是：

隔离不同项目的 Python 和第三方依赖

传统方式：

python -m venv .venv
source .venv/bin/activate
python -m pip install requests
python main.py
deactivate

使用 uv：

uv init
uv add requests
uv run python main.py

最重要的几个概念：

.venv
    项目的虚拟环境

pip
    安装 Python 包

requirements.txt
    传统依赖记录方式

pyproject.toml
    现代 Python 项目配置

uv.lock
    锁定具体依赖版本

uv add
    添加项目依赖

uv run
    在项目环境中运行命令

日常开发推荐养成：

一个项目一个虚拟环境

并且不要把：

.venv

提交到 Git。