虚拟环境¶

当你在 Python 工程中工作时，你可能会有必要用到一个虚拟环境（或类似的机制）来隔离你为每个工程安装的包。

创建一个工程¶

首先，为你的工程创建一个目录。

我通常会在我的主目录下创建一个名为code 的目录。

在这个目录下，我再为每个工程创建一个目录。

// 进入主目录$cd// 创建一个用于存放所有代码工程的目录$mkdircode// 进入 code 目录$cdcode// 创建一个用于存放这个工程的目录$mkdirawesome-project// 进入这个工程的目录$cdawesome-project

创建一个虚拟环境¶

在开始一个 Python 工程的第一时间，在你的工程内部创建一个虚拟环境。

$python-mvenv.venv

$uvvenv

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

激活虚拟环境¶

激活新的虚拟环境来确保你运行的任何 Python 命令或安装的包都能使用到它。

$source.venv/bin/activate

$.venv\Scripts\Activate.ps1

$source.venv/Scripts/activate

检查虚拟环境是否激活¶

检查虚拟环境是否激活 (前面的命令是否生效)。

$whichpython/home/user/code/awesome-project/.venv/bin/python

$Get-CommandpythonC:\Users\user\code\awesome-project\.venv\Scripts\python

升级pip¶

如果你使用pip 来安装包（它是 Python 的默认组件），你应该将它升级 到最新版本。

在安装包时出现的许多奇怪的错误都可以通过先升级pip 来解决。

确保虚拟环境是激活的 (使用上面的命令)，然后运行：

$python-mpipinstall--upgradepip---> 100%

$python-mensurepip--upgrade---> 100%

添加.gitignore¶

如果你使用Git (这是你应该使用的)，添加一个.gitignore 文件来排除你的.venv 中的所有内容。

$echo"*">.venv/.gitignore

*

安装软件包¶

在激活虚拟环境后，你可以在其中安装软件包。

直接安装包¶

如果你急于安装，不想使用文件来声明工程的软件包依赖，你可以直接安装它们。

$pipinstall"fastapi[standard]"---> 100%

$uvpipinstall"fastapi[standard]"---> 100%

从requirements.txt 安装¶

如果你有一个requirements.txt 文件，你可以使用它来安装其中的软件包。

$pipinstall-rrequirements.txt---> 100%

$uvpipinstall-rrequirements.txt---> 100%

fastapi[standard]==0.113.0pydantic==2.8.0

运行程序¶

在你激活虚拟环境后，你可以运行你的程序，它将使用虚拟环境中的 Python 和你在其中安装的软件包。

$pythonmain.pyHello World

配置编辑器¶

你可能会用到编辑器，请确保配置它使用与你创建的相同的虚拟环境（它可能会自动检测到），以便你可以获得自动补全和内联错误提示。

例如：

• VS Code
• PyCharm

退出虚拟环境¶

当你完成工作后，你可以退出虚拟环境。

$deactivate

这样，当你运行python 时，它不会尝试从那个虚拟环境及其已安装的软件包中运行。

开始工作¶

现在你已经准备好开始你的工作了。

为什么要使用虚拟环境¶

你需要安装Python 才能使用 FastAPI。

之后，你需要安装 FastAPI 和你想要使用的任何其他软件包。

要安装软件包，你通常会使用随 Python 一起提供的pip 命令（或类似的替代方案）。

然而，如果你直接使用pip，软件包将被安装在你的全局 Python 环境中（即 Python 的全局安装）。

存在的问题¶

那么，在全局 Python 环境中安装软件包有什么问题呢？

有些时候，你可能会编写许多不同的程序，这些程序依赖于不同的软件包；你所做的一些工程也会依赖于同一软件包的不同版本。😱

例如，你可能会创建一个名为philosophers-stone 的工程，这个程序依赖于另一个名为harry 的软件包，使用版本1。因此，你需要安装harry。

flowchart LR    stone(philosophers-stone) -->|需要| harry-1[harry v1]

然而在此之后，你又创建了另一个名为prisoner-of-azkaban 的工程，这个工程也依赖于harry，但是这个工程需要harry 版本3。

flowchart LR    azkaban(prisoner-of-azkaban) --> |需要| harry-3[harry v3]

那么现在的问题是，如果你将软件包安装在全局环境中而不是在本地虚拟环境中，你将不得不面临选择安装哪个版本的harry 的问题。

如果你想运行philosophers-stone，你需要首先安装harry 版本1，例如：

$pipinstall"harry==1"

然后你将在全局 Python 环境中安装harry 版本1。

flowchart LR    subgraph global[全局环境]        harry-1[harry v1]    end    subgraph stone-project[工程 philosophers-stone]        stone(philosophers-stone) -->|需要| harry-1    end

但是如果你想运行prisoner-of-azkaban，你需要卸载harry 版本1 并安装harry 版本3（或者说，只要你安装版本3 ，版本1 就会自动卸载）。

$pipinstall"harry==3"

于是，你在你的全局 Python 环境中安装了harry 版本3。

如果你再次尝试运行philosophers-stone，有可能它无法正常工作，因为它需要harry 版本1。

flowchart LR    subgraph global[全局环境]        harry-1[<strike>harry v1</strike>]        style harry-1 fill:#ccc,stroke-dasharray: 5 5        harry-3[harry v3]    end    subgraph stone-project[工程 philosophers-stone]        stone(philosophers-stone) -.-x|⛔️| harry-1    end    subgraph azkaban-project[工程 prisoner-of-azkaban]        azkaban(prisoner-of-azkaban) --> |需要| harry-3    end

现在，想象一下，如果有许多其他软件包，它们都是你的工程所依赖的。这是非常难以管理的。你可能会发现，有些工程使用了一些不兼容的软件包版本，而不知道为什么某些东西无法正常工作。

此外，取决于你的操作系统（例如 Linux、Windows、macOS），它可能已经预先安装了 Python。在这种情况下，它可能已经预先安装了一些软件包，这些软件包的特定版本是系统所需的。如果你在全局 Python 环境中安装软件包，你可能会破坏一些随操作系统一起安装的程序。

软件包安装在哪里¶

当你安装 Python 时，它会在你的计算机上创建一些目录，并在这些目录中放一些文件。

其中一些目录负责存放你安装的所有软件包。

当你运行：

// 先别去运行这个命令，这只是一个示例 🤓$pipinstall"fastapi[standard]"---> 100%

这将会从PyPI 下载一个压缩文件，其中包含 FastAPI 代码。

它还会下载 FastAPI 依赖的其他软件包的文件。

然后它会解压所有这些文件，并将它们放在你的计算机上的一个目录中。

默认情况下，它会将下载并解压的这些文件放在随 Python 安装的目录中，这就是全局环境。

什么是虚拟环境¶

解决软件包都安装在全局环境中的问题的方法是为你所做的每个工程使用一个虚拟环境。

虚拟环境是一个目录，与全局环境非常相似，你可以在其中专为某个工程安装软件包。

这样，每个工程都会有自己的虚拟环境（.venv 目录），其中包含自己的软件包。

flowchart TB    subgraph stone-project[工程 philosophers-stone]        stone(philosophers-stone) --->|需要| harry-1        subgraph venv1[.venv]            harry-1[harry v1]        end    end    subgraph azkaban-project[工程 prisoner-of-azkaban]        azkaban(prisoner-of-azkaban) --->|需要| harry-3        subgraph venv2[.venv]            harry-3[harry v3]        end    end    stone-project ~~~ azkaban-project

激活虚拟环境意味着什么¶

当你激活了一个虚拟环境，例如：

$source.venv/bin/activate

$.venv\Scripts\Activate.ps1

$source.venv/Scripts/activate

这个命令会创建或修改一些环境变量，这些环境变量将在接下来的命令中可用。

其中之一是PATH 变量。

激活虚拟环境会将其路径.venv/bin（在 Linux 和 macOS 上）或.venv\Scripts（在 Windows 上）添加到PATH 环境变量中。

假设在激活环境之前，PATH 变量看起来像这样：

/usr/bin:/bin:/usr/sbin:/sbin

C:\Windows\System32

激活虚拟环境后，PATH 变量会变成这样：

/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin

/home/user/code/awesome-project/.venv/bin

/home/user/code/awesome-project/.venv/bin/python

C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32

C:\Users\user\code\awesome-project\.venv\Scripts

C:\Users\user\code\awesome-project\.venv\Scripts\python

一个重要的细节是，虚拟环境路径会被放在PATH 变量的开头。系统会在找到任何其他可用的 Python之前找到它。这样，当你运行python 时，它会使用虚拟环境中的 Python，而不是任何其他python（例如，全局环境中的python）。

激活虚拟环境还会改变其他一些东西，但这是它所做的最重要的事情之一。

检查虚拟环境¶

当你检查虚拟环境是否激活时，例如：

$whichpython/home/user/code/awesome-project/.venv/bin/python

$Get-CommandpythonC:\Users\user\code\awesome-project\.venv\Scripts\python

这意味着将使用的python 程序是在虚拟环境中的那个。

在 Linux 和 macOS 中使用which，在 Windows PowerShell 中使用Get-Command。

这个命令的工作方式是，它会在PATH 环境变量中查找，按顺序逐个路径查找名为python 的程序。一旦找到，它会显示该程序的路径。

最重要的部分是，当你调用python 时，将执行的就是这个确切的 "python"。

因此，你可以确认你是否在正确的虚拟环境中。

为什么要停用虚拟环境¶

例如，你可能正在一个工程philosophers-stone 上工作，激活了该虚拟环境，安装了包并使用了该环境，

然后你想要在另一个工程prisoner-of-azkaban 上工作，

你进入那个工程：

$cd~/code/prisoner-of-azkaban

如果你不去停用philosophers-stone 的虚拟环境，当你在终端中运行python 时，它会尝试使用philosophers-stone 中的 Python。

$cd~/code/prisoner-of-azkaban$pythonmain.py// 导入 sirius 报错，它没有安装 😱Traceback (most recent call last):    File "main.py", line 1, in <module>        import sirius

但是如果你停用虚拟环境并激活prisoner-of-askaban 的新虚拟环境，那么当你运行python 时，它会使用prisoner-of-askaban 中的虚拟环境中的 Python。

$cd~/code/prisoner-of-azkaban// 你不需要在旧目录中操作停用，你可以在任何地方操作停用，甚至在转到另一个工程之后 😎$deactivate// 激活 prisoner-of-azkaban/.venv 中的虚拟环境 🚀$source.venv/bin/activate// 现在当你运行 python 时，它会在这个虚拟环境中找到安装的 sirius 包 ✨$pythonmain.pyI solemnly swear 🐺

替代方案¶

这是一个简单的指南，可以帮助你入门并教会你如何理解一切底层的东西。

有许多替代方案来管理虚拟环境、包依赖（requirements）、工程。

一旦你准备好并想要使用一个工具来管理整个工程、包依赖、虚拟环境等，建议你尝试uv。

uv 可以做很多事情，它可以：

• 为你安装 Python，包括不同的版本
• 为你的工程管理虚拟环境
• 安装软件包
• 为你的工程管理软件包的依赖和版本
• 确保你有一个确切的软件包和版本集合来安装，包括它们的依赖项，这样你就可以确保在生产中运行你的工程与在开发时在你的计算机上运行的工程完全相同，这被称为锁定
• 还有很多其他功能

结论¶

如果你读过并理解了所有这些，现在你对虚拟环境的了解比很多开发者都要多。🤓

在未来当你调试看起来复杂的东西时，了解这些细节很可能会有用，你会知道它是如何在底层工作的。😎