当你参与 Python 项目时，可能需要使用虚拟环境（或类似机制）来隔离每个项目安装的软件包。

  • 虚拟环境不同于环境变量 。
  • 环境变量是系统中程序可以使用的一个变量。
  • 虚拟环境是一个包含一些文件的目录。

  • 本页将教你如何使用虚拟环境及其工作原理。
  • 如果你准备好采用一个能帮你管理一切的工具（包括安装 Python），可以试试uv。

创建一个项目

首先，为你的项目创建一个目录。
我通常会在我的主目录/用户目录里创建一个名为code的目录。
在那个里面，我为每个项目创建一个目录。

1
2
3
4
5
6
7
8
9
10
# 💬 Go to the home directory
cd
# 💬 Create a directory for all your code projects
mkdir code
# 💬 Enter into that code directory
cd code
# 💬 Create a directory for this project
mkdir awesome-project
# 💬 Enter into that project directory
cd awesome-project

创建虚拟环境

当你第一次开始做 Python 项目时，在项目内创建一个虚拟环境。

你只需要每个项目做一次 ，不需要每次工作。

要创建虚拟环境，可以使用 Python 自带的 venv 模块。

1
python -m venv .venv

命令含义
  • python：使用名为 Python 的程序
  • -m：调用一个模块作为脚本，我们告诉它下一个模块是哪个
  • venv：使用通常自装的 Python 模块 Venv
  • .venv：在新的目录 .venv 中创建虚拟环境

如果你安装了uv，可以用它来创建虚拟环境。

1
uv venv

  • 默认情况下，uv 会在一个名为 .venv 的目录中创建一个虚拟环境。
  • 但你可以通过传递一个带有目录名的额外参数自定义。

该命令在名为 .venv 的目录中创建一个新的虚拟环境。

.venv 或其他名称

你可以在不同的目录里创建虚拟环境，但有个惯例叫它.venv。

激活虚拟环境

激活新的虚拟环境，这样你运行的任何 Python 命令或软件包都会使用它。

每次启动新的终端会话来处理项目时都要这样做。

1
source .venv/bin/activate
1
.venv\Scripts\Activate.ps1

或者如果你使用 Windows 版 Bash（例如 Git Bash），你可以使用以下命令：）：

1
source .venv/Scripts/activate

  • 每次在该环境中安装新包时，重新激活该环境。
  • 这样可以确保如果你使用该包安装的终端（CLI）程序 ，你使用的是你虚拟环境中的那个，而不是其他可以全局安装的程序，可能版本可能与你需要的版本不同。

检查虚拟环境是否激活

检查虚拟环境是否处于激活状态（之前的命令是否有效）。

这是可选的，但这是检查一切正常运行、是否使用你预期的虚拟环境的好方法。

1
2
$ which python
> /home/user/code/awesome-project/.venv/bin/python

如果它显示了 python 二进制文件在 .venv/bin/python，在你的项目里（这里指 awesome-project），那说明它能用。🎉

1
2
$ Get-Command python
> C:\Users\user\code\awesome-project\.venv\Scripts\python

如果它显示了 python 二进制文件在 .venv\Scripts\python 的项目内（这里指 awesome-project），那说明它能用。🎉

升级pip

如果你用 UV，你会用它来安装东西，而不是 pip，所以不需要升级 pip。😎

如果你用 pip 安装包（Python 默认自带），建议升级到最新版本。
安装包时的许多特殊错误只需先升级 pip 就能解决。

通常你会在创建虚拟环境后做一次 。


确保虚拟环境处于激活状态（使用上述命令），然后运行：
1
python -m pip install --upgrade pip

添加 .gitignore

如果你用的是 Git（你应该用），添加一个.gitignore 文件，把 .venv 里的所有内容排除在 Git 之外。

如果你用 UV 创建了虚拟环境，它已经帮你做到了，你可以跳过这一步。😎


在创建虚拟环境后，先做一次。


1
echo "*" > .venv/.gitignore

命令含义
  • echo "*"：会”打印”终端中的文本 *（下一部分会稍微改变）
  • >：如果在 > 左侧的命令打印到终端，任何内容都不应被打印，而是写入 > 右侧的文件
  • .gitignore：文本应写入的文件名称
    而 * 对于 Git 来说，意思是“一切”。所以，它会忽略 .venv 目录中的所有内容。
    该命令会创建一个包含以下内容的 .gitignore 文件：
    1
    *

安装包

激活环境后，你可以在里面安装包。

  • 安装或升级项目所需的软件包时，只需这样做一次 。
  • 如果你需要升级版本或添加新软件包，你会再做一次 。

直接安装包

如果你很赶时间，不想用文件来声明项目包的需求，可以直接安装它们。

把程序需要的包和版本放进文件里（比如 requirements.txt 或 pyproject.toml）是个（非常）好主意。

1
pip install <package>

如果你有uv：

1
uv pip install <package>

从 requirements.txt 安装包

如果你有 requirements.txt，现在可以用它来安装它的包。

1
pip install -r requirements.txt

如果你有uv：

1
uv pip install -r requirements.txt

requirements.txt

包含某些包裹的 requirements.txt 可能如下：

1
2
fastapi[standard]==0.113.0
pydantic==2.8.0

运行程序

激活虚拟环境后，你可以运行程序，它会在虚拟环境中使用带有你安装的包的 Python。

1
2
$ python main.py
> Hello World

配置你的编辑器

你可能会用编辑器，确保配置它使用你创建的同一个虚拟环境（它很可能会自动检测），这样你才能获得自动补全和内联错误。
例如：

  • VS Code
  • PyCharm

    通常你只需要做一次 ，就是创建虚拟环境时。

关闭虚拟环境

完成项目后，你可以关闭虚拟环境。

1
deactivate

这样，当你运行 python 时，它就不会尝试从那个安装了包的虚拟环境中运行。

删除虚拟环境

删除虚拟环境时，请确保关闭虚拟环境。

1
rm -rf .venv