Python venv 虚拟环境入门:创建、激活与日常使用

开篇:为什么每个项目都需要一个虚拟环境

刚学 Python 的人通常只有一个全局环境:系统里装着一个 Python,所有第三方包都往这一个环境里塞。项目少的时候相安无事,项目一多,麻烦立刻找上门。先看一个非常真实的场景:你手头维护着两个项目,项目 A 是两年前上线的老服务,代码里写死了某个库的老版本行为,只能跑在 requests 2.20 上;项目 B 是新接的需求,要用到某 SDK,而这个 SDK 要求 requests 不低于 2.28。全局环境只有一个,你给 B 升级了 requests,A 当晚就在生产上报错;你把版本降回去,B 又启动不了。这就是典型的全局环境污染:所有项目共用一份 site-packages,版本只能有一个赢家。

污染还不止于版本冲突。为了跑通某个教程随手装的包、试验某个框架留下的残余依赖、被其他包顺带升级或降级的公共依赖,都会让全局环境变成一锅大杂烩。更糟的是系统自身的工具也可能依赖系统 Python:Linux 发行版的不少管理脚本直接调用 /usr/bin/python3 及其库,你往系统环境里乱装、乱升级,一旦把某个基础库弄坏,影响的就不只是你自己的项目了。还有一种常见翻车现场:新同事接手项目,你说"装一下依赖就能跑",他装完却怎么也跑不起来,因为你的全局环境里还躺着三个从未写进任何清单、但代码恰好 import 到了的包。

虚拟环境解决的正是这个问题。它的思路简单到近乎朴素:给每个项目单独建一个目录,里面放一份独立的 Python 解释器入口和一份独立的包安装位置,项目之间互不干扰。你可以把虚拟环境理解成给项目租的单间公寓:家具(依赖包)各买各的,邻居装修不会拆了你家的墙。Python 从 3.3 开始把 venv 模块收进了标准库,不需要额外安装任何工具,一条命令就能建。本文面向刚开始正经写项目、或者已经被全局环境坑过一次的开发者,把创建、激活、日常使用、退出与重建这条主线一次走通,并把 Linux、macOS、Windows 三个平台的差异都交代清楚。

前置条件

开始之前只需要确认两件事。第一,系统里装有 Python 3.3 或更高版本(现在的发行版基本都是 3.8 以上,这一条几乎不用担心)。第二,知道如何打开终端:Linux/macOS 用系统自带的终端应用,Windows 可以用命令提示符(cmd)、PowerShell 或 Git Bash,本文三种都会覆盖。先确认版本:

# Linux / macOS
python3 --version

# Windows(cmd 或 PowerShell)
py --version
python --version

能打印出 Python 3.x.x 就可以继续。补充一句:Debian/Ubuntu 用户如果创建虚拟环境时报 ensurepip 相关的错误,多半是系统把 venv 支持拆成了单独的软件包,需要先执行 sudo apt install python3-venv(或带版本号的 python3.12-venv)补上,这是 Debian 系独有的小坑,后文常见问题里还会再提。

第一步:创建虚拟环境

进入你的项目目录,在项目根目录下创建虚拟环境。约定俗成的做法是把环境目录命名为 .venv(以点开头,在文件管理器和 ls 默认视图里会隐藏起来,不碍眼;很多工具也会自动识别这个名字)。命令如下:

# Linux / macOS
cd ~/projects/demo
python3 -m venv .venv

# Windows(cmd 或 PowerShell)
cd C:\Users\demo\projects\demo
py -m venv .venv
# 若 py 启动器不可用,也可以用 python -m venv .venv

逐段拆解这条命令:python3 -m venv 的意思是"以模块方式运行标准库里的 venv 模块";后面的 .venv 是目标目录名,也就是环境建在哪里、叫什么名字。执行后没有任何输出是正常的,目录 .venv 会被创建出来,里面已经放好了一整套东西。Windows 上的 py 是 Python 官方安装包自带的启动器,它能自动找到系统里安装的 Python,在装了多个版本时还可以用 py -3.12 -m venv .venv 指定用哪个版本建环境;如果你的 Windows 上 py 不可用,用 python -m venv .venv 效果一样,前提是 python 已加入 PATH。

这里还要强调一个观念:虚拟环境目录应该跟着项目走,而不是集中放在某个全局位置统一管理。把 .venv 建在项目根目录里,好处是项目搬到哪儿、环境就跟到哪儿,删项目时环境一并消失,不会留下一堆不知道属于谁的孤儿环境。同时务必记住:.venv 目录不要提交到 Git 仓库。在项目的 .gitignore 里加上一行 .venv/,理由很实际:环境里包含大量二进制文件和与操作系统绑定的路径,换台机器根本无法直接复用,体积还动辄上百 MB。环境本身不是资产,能重建环境的"配方"(也就是后文会提到的 requirements.txt)才是资产。

第二步:激活虚拟环境

创建只是把环境建好,日常使用前必须先"激活"它。激活做的事其实很朴素:临时修改当前终端会话的环境变量,把 .venv 里的解释器和工具路径顶到 PATH 最前面,并设置一个标记让提示符显示当前环境名。注意关键词:当前终端会话。激活只对执行了激活命令的这一个终端窗口有效,新开的终端、另一个窗口里的终端都不会自动进入环境,这是新手最常见的困惑来源之一。

Linux 与 macOS(bash / zsh)

cd ~/projects/demo
source .venv/bin/activate
# 等价的简写:. .venv/bin/activate

macOS 现在的默认 shell 是 zsh,Linux 多为 bash,两者激活命令完全一致,都是 source bin/activate。source 的作用是让脚本在当前 shell 进程里执行,这样它修改的环境变量才能保留下来;如果直接运行 .venv/bin/activate,脚本会在子进程里跑,改完就退出,当前终端什么都不会变,所以必须用 source 或等价的点号简写。

Windows:cmd

cd C:\Users\demo\projects\demo
.venv\Scripts\activate.bat

cmd 里用的是 Scripts 目录下的 activate.bat 批处理文件,直接写路径回车即可,不需要任何前缀命令。注意 Windows 下目录名是 Scripts 而不是 bin,这是两个平台最直观的差异之一。

Windows:PowerShell

cd C:\Users\demo\projects\demo
.venv\Scripts\Activate.ps1

PowerShell 对应的是 Activate.ps1(注意首字母大写只是文件名习惯,PowerShell 不区分大小写)。第一次在 PowerShell 里激活时,很多人会撞上一堵墙:系统报"无法加载文件,因为在此系统上禁止运行脚本"。这是 PowerShell 的执行策略在拦截未签名脚本,并不是环境坏了。解决办法是给当前用户放宽执行策略:执行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser,回答 Y 确认即可。这个设置只需做一次,作用范围是当前用户,不需要管理员权限。改完之后重新运行激活脚本就能顺利进入。

Windows:Git Bash

装了 Git for Windows 的人常用 Git Bash,它的激活方式最容易踩坑:文件既不是 bin/activate 也不是 activate.bat,而是 Scripts 目录下的 activate(无扩展名),并且要用 source 执行:

cd /c/Users/demo/projects/demo
source .venv/Scripts/activate

也就是说 Git Bash 是"Windows 的目录结构(Scripts)加 Unix 的激活姿势(source)"的混合体。如果你在 Git Bash 里误用了 bin/activate,系统只会告诉你文件不存在,对着报错愣半天都想不到是目录名的问题。

第三步:确认激活成功,并理解发生了什么

激活成功最明显的标志是命令行提示符前面多了一个括号包裹的环境名,大致长这样:

# 激活前
demo@ubuntu:~/projects/demo$

# 激活后
(.venv) demo@ubuntu:~/projects/demo$

除了看提示符,更可靠的验证方式是问终端:现在敲 python 用的是哪个 python。不同平台命令略有不同:

# Linux / macOS / Git Bash
which python
# 输出应指向项目内的环境:/home/demo/projects/demo/.venv/bin/python

# Windows cmd
where python
# 第一行应是 C:\Users\demo\projects\demo\.venv\Scripts\python.exe

# Windows PowerShell
(Get-Command python).Source

只要输出路径落在项目的 .venv 目录里,就说明这个终端已经"住进"虚拟环境了。此后再执行 pip install,包装进的是环境的专属目录;执行 python,启动的也是环境内的解释器。你可以顺手验证一件事:此时 pip list 看到的包应该非常干净,只有 pip 本身(新版本还会带 setuptools 的处理差异,但总体上两只手数得过来),和你全局环境里那一长串清单形成鲜明对比,这就是"独立"的实际含义。

第四步:看懂虚拟环境的目录结构

花一分钟看懂 .venv 里有什么,后续排错会轻松很多。整体结构在两个平台上是对应的:

.venv/
├── pyvenv.cfg          # 环境的身份证:记录它基于哪个 Python 创建
├── bin/                # Linux / macOS:解释器与工具入口
│   ├── python          # 指向基础解释器的链接/副本
│   ├── pip
│   └── activate        # 激活脚本(另有 activate.csh、activate.fish 等)
├── lib/
│   └── python3.12/
│       └── site-packages/   # pip 安装的第三方包实际存放处
└── include/

# Windows 对应结构
.venv/
├── pyvenv.cfg
├── Scripts\            # 相当于 bin:python.exe、pip.exe、activate.bat、Activate.ps1
└── Lib\site-packages\

最值得认识的是 pyvenv.cfg 这个小文件,用文本编辑器打开它,内容大致如下:

home = /usr/bin
include-system-site-packages = false
version = 3.12.4

home 记录了创建这个环境所用的基础 Python 所在位置,环境里的 python 启动时会顺着它找到标准库;include-system-site-packages 为 false 表示与全局包隔离,这正是我们要的默认行为;version 是基础解释器的版本。这份文件也解释了两个常见现象:其一,把 .venv 整个目录拷贝或移动到别的位置后环境会失效,因为里面的脚本和配置写死了原始绝对路径;其二,卸载或移动了系统 Python 之后,依赖它的虚拟环境会跟着打不开。所以请记住:虚拟环境不可搬家、不可改名,想换位置就删掉重建(下一节细说)。另外,site-packages 是 pip 装包的落点,当你怀疑某个包装没装对、想看看它到底装了什么文件时,直接来这里翻是最靠谱的。

第五步:日常使用与退出

激活状态下的日常操作和平时没有任何区别,只是所有动作都作用于当前环境:

# 安装包(装进当前虚拟环境)
python -m pip install requests

# 查看环境里装了什么
python -m pip list

# 运行项目代码
python app.py

这里特意写成 python -m pip 而不是直接 pip:在环境已激活时两者等价,但 python -m pip 能保证调用的一定是"当前这个 python 对应的 pip",在系统里装了多个 Python 的机器上可以避免 pip 和 python 对不上的经典混乱,值得养成习惯。用完之后,退出环境只需要一条命令,所有平台通用:

deactivate

执行后提示符前的 (.venv) 前缀消失,PATH 恢复原样,python 重新指回全局解释器。需要说明的是 deactivate 不是命令文件,而是激活脚本在当前 shell 里定义的一个函数,所以它只在已激活的终端里存在;没激活时敲它只会得到"命令不存在",这属于正常现象。另外,直接关掉终端窗口也等同于退出,环境变量本来就只活在这个会话里,不用担心有什么残留状态需要清理。

第六步:删除即重建——对待环境的正确心态

虚拟环境用坏了怎么办?答案是:删掉,重建。整个 .venv 只是一个普通目录,不写注册表、不动系统配置,删除它对系统毫无影响:

# 先退出环境
deactivate

# Linux / macOS:删除后按原命令重建
rm -rf .venv
python3 -m venv .venv

# Windows PowerShell 删除
Remove-Item -Recurse -Force .venv
py -m venv .venv

这种"一次性用品"的心态恰恰是虚拟环境设计的精髓:环境不值得抢修,因为重建只要几秒。环境损坏的典型症状包括:移动过项目目录导致解释器路径失效、基础 Python 被升级或卸载、pip 把依赖关系装成一团乱麻。遇到这些情况,与其对着报错逐个猜,不如先把当前依赖导出留底,再删掉重建、按清单装回,十分钟解决战斗。至于如何把依赖导出成 requirements.txt 清单、又如何凭清单一键还原,是下一篇《依赖管理:pip 与 requirements.txt 实战》的主題,本文只点到为止:记住环境可弃、清单必存,就抓住了 venv 工作流的骨架。

第七步:在 VS Code 里选择解释器

如果你用 VS Code 写 Python,还需要多做一步:告诉编辑器这个项目用哪个解释器,否则编辑器可能仍拿全局 Python 做代码检查和运行,出现"终端里能跑、编辑器里飘红"的怪象。做法是打开命令面板(Ctrl+Shift+P,macOS 为 Cmd+Shift+P),输入 Python: Select Interpreter 并回车,在列表里选择路径中带有 .venv 的那一项;如果列表里没出现,点"输入解释器路径"手动定位到 .venv/bin/python(Windows 为 .venv\Scripts\python.exe)。选择结果会记录在工作区的 .vscode/settings.json 里,之后每次打开这个项目文件夹都会自动套用。顺带一提,VS Code 的 Python 扩展在识别到工作区里新建的 .venv 后,新开的集成终端常常会自动激活环境,省去手动 source 的一步,但如果发现提示符没有前缀,手动激活一次即可。

验证:走一遍完整自检

把下面这组动作从头到尾走一遍,全对就说明你真正掌握了 venv 的日常循环:

cd ~/projects/demo
python3 -m venv .venv
source .venv/bin/activate
which python          # 路径必须落在 ~/projects/demo/.venv/bin/ 下
python -m pip list    # 清单应非常短,只有 pip 等寥寥几个
python -m pip install requests
python -c "import requests; print(requests.__version__)"
deactivate
which python          # 应恢复为系统路径,如 /usr/bin/python3

最后一条 import 验证很关键:它同时证明了包装对了地方、且在激活状态下能被当前解释器找到。如果激活后 import 仍报 ModuleNotFoundError,优先怀疑终端没有真正激活(比如新开了一个窗口),而不是包没装好。

常见问题

问题一:激活后提示符没有出现 (.venv) 前缀

先确认你执行的激活脚本路径与所在平台匹配:Linux/macOS 是 bin/activate,Windows cmd 是 Scripts\activate.bat,PowerShell 是 Scripts\Activate.ps1,Git Bash 是 Scripts/activate。其次确认命令是在项目目录(或写对了相对/绝对路径)下执行的,路径写错时 bash 会明确报 No such file or directory。还要提醒:激活只对当前终端有效,如果你激活完又新开了一个终端窗口,新窗口里没有前缀是完全正常的,重新激活即可。

问题二:PowerShell 报"禁止运行脚本"

如前文所述,这是执行策略拦截,与环境本身无关。执行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 并确认,之后重新激活。该设置对当前用户永久生效,只需做一次;不要为了省事去改全系统的策略范围。

问题三:Ubuntu/Debian 创建时报 ensurepip is not available

这是 Debian 系把 venv 拆包的已知行为:执行 sudo apt install python3-venv(或与你的版本对应的 python3.12-venv),装完后删掉残缺的 .venv 目录重新创建即可。其他发行版和 macOS、Windows 一般不会遇到。

问题四:把项目拷到另一台电脑后,环境打不开了

这是预期行为而非故障:虚拟环境里写死了创建机器上的绝对路径,且包含平台相关的二进制,本来就不可移植。正确做法是只拷贝源码和 requirements.txt,到新机器上重新 python -m venv 建环境再按清单安装。再次强调,.venv 不要进 Git 仓库,道理相同。

问题五:创建命令里的几个参数是什么意思

venv 还支持少量可选参数,日常基本用不上,这里只做简述以免你被老教程误导。--system-site-packages 会让新环境能直接使用全局环境的包,隔离性随之打折,只在个别需要复用系统级大包的特殊场景才考虑,日常不要加;--without-pip 会创建一个不带 pip 的环境,通常是给打算改用其他装包方式的高级用户准备的,新手加上它只会让自己没法装包。此外还有 --prompt 可以自定义激活后提示符里显示的名字,纯属美观需求。记住一条原则:日常使用就一条光秃秃的 python3 -m venv .venv,参数越少越不容易给自己挖坑。

小结

本文把 venv 的日常主线完整走了一遍:全局环境污染来自"所有项目共用一份包",解法是给每个项目建独立环境;创建只需 python3 -m venv .venv(Windows 用 py -m venv .venv);激活方式按平台区分——bash/zsh 用 source bin/activate,cmd 用 Scripts\activate.bat,PowerShell 用 Scripts\Activate.ps1 且首次可能要放宽执行策略,Git Bash 用 source Scripts/activate;激活后靠提示符前缀和 which python 双重确认;pyvenv.cfg 记录了环境的出身,也决定了它不可搬家;退出用 deactivate;环境坏了不要修,删掉重建才是正道;用 VS Code 时记得 Select Interpreter 选到 .venv 的解释器。下一篇我们解决下一个问题:如何把环境里的依赖导出成 requirements.txt,让这套环境能在任何机器上一键复原。

发表回复

后才能评论