平时开发Python项目时最让人头疼的往往不是业务逻辑本身而是依赖管理。尤其当你同时维护着多个项目这个要Requests 2.x那个要Requests 3.x还有的项目必须锁死在Python 3.6装新库怕影响旧项目不装又无法推进新需求。我之前有段时间一直被这个问题折腾直到真正搞懂了virtualenv才算是把开发环境这块理顺了。这篇就基于我的实际使用经验把virtualenv从安装到日常使用的完整链路、里面容易踩的坑和背后的工作原理都拆开讲清楚。1. 为什么说virtualenv是Python开发的“隔离舱”很多人刚接触Python时都是直接在全局环境里pip install这在一台机器只跑一个项目的时候问题不大但一旦项目多起来依赖冲突几乎是必然的。我见过最典型的案例某公司的内部工具链依赖Django 1.11而另一个新项目需要Django 3.2两边都用全局环境结果就是装完新项目旧工具直接跑不起来报错一堆。virtualenv解决的就是这个核心矛盾——它为每一个项目创建一个独立的Python运行环境在这个环境里你可以任意安装、升级、删除第三方库而完全不影响全局环境和其他项目。我更喜欢叫它“隔离舱”因为它的作用和船舱水密隔断是一个逻辑某个舱进水了不会导致整条船沉掉。你的某个项目把环境搞坏了其他项目照样毫发无损。从技术原理上说virtualenv做的事情并不神秘。它会复制一份当前Python解释器或者你指定的某个版本的解释器到项目目录下的venv文件夹中同时建立独立的site-packages目录。当你激活这个虚拟环境时它的核心动作就是修改PATH环境变量把venv/Scripts或者venv/bin这个路径挪到最前面这样你在终端里敲python、pip实际执行到的就是虚拟环境里的那一份而不是全局的。这套机制的关键点在于解释器隔离虚拟环境里的python指向的是venv目录下的解释器不是系统路径下的那个。包管理隔离pip install安装的第三方库会写入虚拟环境自己的site-packages全局环境干干净净。无需系统权限很多服务器上你没有root权限全局pip安装会报权限错误但虚拟环境是装在自己项目目录下的不需要任何额外权限。注意virtualenv创建出的环境不是完整的Python发行版它更像是“复制了一套解释器纯净的第三方包目录”标准库依然是继承自你指定的那个Python版本的。这个理解很重要后面排查问题会用到。所以如果你是以下这几类开发者我建议你直接开始用virtualenv同时维护多个Python项目且依赖各不相同。需要在没有管理员权限的服务器上部署应用。想用一个固定版本的Python测试自己的代码在不同解释器下的表现。刚学Python不久希望从一开始就养成干净的环境管理习惯。2. 安装在开始之前virtualenv与系统Python的关系先说结论virtualenv本身就是一个普通的Python第三方库通过pip装到全局环境或者用户目录下就行。它不要求你预先创建任何虚拟环境恰恰相反它是“创建虚拟环境”的工具。安装命令非常简单但在这之前有两点需要先确认好。第一确认你的Python版本。virtualenv对Python 2.7和Python 3都有支持但如果你还在用Python 2.7要注意新版本的virtualenv可能已经不兼容了。官方是这么说的Python 2.7的支持在virtualenv 20.x早期版本中保留但后续版本已经放弃。所以如果你还在维护Python 2的老项目我建议用virtualenv20.16.6这个版本实测还算稳定。第二确认pip是否可用。现在的Python安装包一般都会自带pip但某些精简安装或者Linux系统自带的Python可能没有。你可以执行一下pip --version如果提示找不到命令可能需要先通过ensurepip或者操作系统的包管理器把pip装上。确认无误后安装virtualenvpip install virtualenv安装完成后验证一下virtualenv --version我实际操作中更推荐用python -m virtualenv这种方式来调用它而不是直接敲virtualenv命令。原因有两个一是当你系统里有多个Python版本时用python -m virtualenv能明确指定是“当前这个python解释器”在创建环境不会因为PATH里到底哪个virtualenv在前而弄得糊涂二是很多人喜欢给命令起别名结果时间长了都不知道实际调的是哪个版本。python -m virtualenv --version如果这一步能正确输出版本号说明工具已经就绪。接下来就可以创建虚拟环境了。2.1 用国内镜像源提速如果是给公司内网机器或者自己的服务器装网络情况可能不太稳定。我在境内部署时常用清华的镜像源来加速pip install virtualenv -i https://pypi.tuna.tsinghua.edu.cn/simple这里提醒一句使用镜像源的时候留意一下你所在网络环境的访问规则不同地区、不同网络能访问的源不完全一样。通常清华、阿里云这些镜像都是可用的选一个能稳定访问的即可。3. 创建虚拟环境的完整步骤与参数选择安装好后进入你的项目目录执行如下命令创建虚拟环境cd /path/to/your/project python -m virtualenv venv这条命令会创建一个名为venv的文件夹里面就是一套独立的Python环境。这个文件夹的名称可以自己定不过我建议统一用venv、.venv或者env后面配置.gitignore和IDE识别都会省心很多。创建过程会有输出信息大意是“创建了Python X环境的虚拟环境”之类。如果你用的是virtualenv 20.x还会提示你创建的虚拟环境里包含pip、setuptools等核心工具。这就意味着你不需要再手动给虚拟环境装pip——它已经自带了。创建完以后目录结构大致是venv/ ├── bin/ # Linux/macOS下的可执行文件python、pip都在这里 │ ├── activate │ ├── python │ ├── pip │ └── ... ├── include/ ├── lib/ # 实际存放第三方包的site-packages所在目录 │ └── python3.x/ └── pyvenv.cfg # 配置文件记录了指向哪个基础Python版本Windows下略有不同Scripts目录代替了binactivate脚本在Scripts里。3.1 常用参数详解--python、--system-site-packages、--no-pipvirtualenv创建环境时支持不少参数我只挑几个日常真正用得上、面向实战场景的说一下。--python或-p指定用哪个Python解释器来创建环境。这在你有多个Python版本时会非常有用。比如你系统里同时装了Python 3.8和Python 3.11但项目要求3.8可以这样指定python -m virtualenv -p python3.8 venv甚至可以直接指向解释器的具体路径python -m virtualenv -p /usr/local/bin/python3.8 venv指定路径的方式更精确避免系统里存在多个同名python3.8时搞错。Windows下路径类似C:\Python38\python.exe。--system-site-packages默认情况下虚拟环境是看不到全局环境里已安装的第三方包的。加上这个参数后虚拟环境会“继承”全局site-packages里的所有包。这个参数有时候很实用——例如你全局里已经装好了一个体积很大的库而项目又正好需要它为了省磁盘空间和安装时间可以这样隔离但共享。但我要提醒一下这个参数也容易引入隐蔽的问题。因为虚拟环境里一旦激活了这个选项你在安装新包时它可能和全局的旧版本产生冲突而这种冲突还不像完全隔离那样好查。所以我个人习惯是除非有明确理由否则不用这个参数。绝大多数情况下我们需要的是彻底隔离。--no-pip、--no-setuptools创建出来的虚拟环境不自带pip或setuptools。这种一般出现在你想做一个最最干净的环境然后用get-pip.py或者自己后面手动装工具的场景。普通情况下不需要默认带上pip才是最常见的做法。3.2 激活与退出看似简单其实藏着一个关键点创建完虚拟环境后你要“进入”这个环境才能使用它。进入的动作叫激活activate。Linux/macOS下执行source venv/bin/activateWindows命令行下执行venv\Scripts\activate.batWindows PowerShell下执行venv\Scripts\Activate.ps1激活成功后命令行提示符前面会出现一个(venv)前缀例如(venv) userhostname:/path/to/project$看到这个前缀就说明当前终端会话已经处于虚拟环境之中。此时你敲python、pip、pytest等所有命令跑的都是这个虚拟环境里的那一份。退出虚拟环境只需要执行deactivate命令敲完(venv)前缀消失就回到了全局环境。这里有个关键点很多人没意识到激活只是改变了当前终端的PATH环境变量它不影响其他终端窗口也不会改变你项目的任何文件。也就是说你开一个新的终端窗口想用虚拟环境的话得在新窗口里重新执行一遍激活命令。这个特性在日常使用中要记牢不然就容易出现“明明刚才还能运行换个窗口就不行了”的困惑。4. 日常使用virtualenv最绕不开的几个操作创建和激活只是第一步真正实用的是把虚拟环境融入日常开发流程。我把平时最常用到的操作整理出来这些动作我几乎每个项目都会用到。4.1 用pip freeze锁定依赖配合requirements.txt实现环境复现当你在这个虚拟环境里安装好了项目所需的所有第三方库可以用一条命令把当前环境里所有的包连同版本号导出到一个文件pip freeze requirements.txt生成的requirements.txt长这样Django3.2.19 requests2.31.0 gunicorn20.1.0这份文件就是项目的“依赖快照”。换一台机器、换一个同事的电脑或者部署到服务器上只需要pip install -r requirements.txt就能把一模一样的依赖环境重建出来。这意味着你根本不需要把venv这个大文件夹拷给别人只要一个几十行的文本文件就能让环境在任何机器上重现。我自己的习惯是凡是项目往仓库里提交requirements.txt一定要跟着提交。venv目录则加入.gitignore绝对不提交。一个典型的.gitignore片段长这样venv/ .venv/ __pycache__/ *.pyc4.2 升级virtualenv本身与虚拟环境的关系virtualenv这个工具本身升级了已经创建好的虚拟环境并不会自动跟着升级。virtualenv的作用只是“创建”创建完成后虚拟环境就自成一体了。所以如果你看到新版本virtualenv发布了别急着去前提下已存在的环境做什么操作。要升级的只是你拿来创建虚拟环境的那个工具而不是某个具体的虚拟环境。想用新版virtualenv创建环境重新创建即可旧的项目继续用旧环境没有任何问题。4.3 在PyCharm或VS Code里指定虚拟环境现代IDE都支持直接使用虚拟环境不需要每次都在终端里激活。以PyCharm为例打开项目设置里的Python Interpreter选择“Existing Environment”把路径指到venv/bin/python # Linux/macOS venv\Scripts\python.exe # Windows之后PyCharm的终端、运行按钮都会自动使用这个虚拟环境的解释器。VS Code则是通过命令面板里“Python: Select Interpreter”选择对应路径。这样下来日常写代码就完全不用手动激活了IDE帮你处理好了一切。4.4 删除与重建虚拟环境坏了怎么办虚拟环境里的包装乱了、版本冲突解不开了或者Python升级后环境出现莫名其妙的问题最干脆的解决办法就是删掉重来deactivate rm -rf venv python -m virtualenv venv pip install -r requirements.txt整个过程不会超过两分钟而且有requirements.txt保障重建后依赖完全一致。这就是虚拟环境最大的优势之一——环境是“可再生资源”不值得你去修复一个破损的环境坏了大不了重建。5. 多版本Python场景下virtualenv的配合策略上面提到过-p参数可以指定Python版本。这一节展开讲讲项目里需要多个Python版本时怎么搭配virtualenv最顺手。先说一个常见场景你可能需要在Python 3.8上验证代码兼容性同时又在Python 3.11上开发新功能。如果你直接用virtualenv可以创建两个不同名字的环境python -m virtualenv -p python3.8 venv38 python -m virtualenv -p python3.11 venv311需要用哪个环境就激活哪个。这样两个环境的第三方依赖可以完全分开互不干扰。不过如果你频繁要切换不同版本的Python我建议再配一个工具pyenv。pyenv负责管理“安装哪些版本的Python”virtualenv则负责“基于某个版本创建隔离环境”。两者的分工可以说非常清晰pyenv决定你的项目用哪个Python解释器virtualenv决定那个解释器下的第三方包装在哪里、和全局环境怎么隔离我的习惯是先通过pyenv安装好需要的Python版本然后在项目里用virtualenv基于对应版本创建环境。在旧版本Python上测试时这个组合非常可靠测试完一点痕迹都不留在全局。还可以简单提一下conda。如果你本来就用conda管理环境和包那virtualenv在conda体系里其实是多余的因为conda自带环境管理。但对于不用conda的普通pip用户来说virtualenv依然是经典且通用的选择。这两条路径没有绝对的高下之分只是生态偏好不同而已。6. virtualenv、venv、virtualenvwrapper、pipenv、poetry的取舍标题是“virtualenv的安装”但其实很多新手会把这一堆名词都搞混。我自己刚开始也花了一段时间才理清楚这里就一次性说透。6.1 virtualenv与内置venv的关系Python 3.3以后标准库中新增了venv模块它提供了类似virtualenv的虚拟环境能力。也就是说如果你用的Python版本是3.3及以上理论上可以不安装virtualenv直接用python -m venv venv那为什么还要用virtualenv最核心的区别是两者创建的“环境级别”有别venv是标准库自带的使用方便但对于Python老版本2.x和3.3以下不支持而virtualenv是第三方库可以支持更老版本的Python而且提供了额外的灵活性和跨版本支持。virtualenv还支持通过--system-site-packages等参数做更细粒度的配置以及提供了更完善的全局工具整合能力。对于现代Python项目3.6以上说实话只用venv也完全够用。但你如果需要在同一台机器上管理多个老版本Python项目virtualenv仍然是更方便的选择。6.2 virtualenvwrapper带来的效率提升virtualenv本身有个小小的不便每次要用环境都得手动去找路径然后source。项目多了效率就下来了。virtualenvwrapper就是解决这个问题的pip install virtualenvwrapper安装后通过配置几条环境变量WORKON_HOME等你就能用workon project1命令直接激活对应的虚拟环境不用记路径、不用手动source。还有lsvirtualenv、rmvirtualenv、cpvirtualenv等一系列管理命令。这套工具在Linux服务器管理多个项目时效率提升非常明显。我见过不少人直接在.bashrc或.zshrc里写死一处配置然后所有的项目环境都通过virtualenvwrapper来管理体验很流畅。Windows上则对应的是virtualenvwrapper-win。6.3 pipenv与poetry更现代但更需要理解底层pipenv和poetry是virtualenv和pip的上层封装它们不只是管理虚拟环境还把依赖解析、锁定、打包等一并纳入。比如poetry会用pyproject.toml记录依赖声明用poetry.lock锁定精确版本。这些工具本身确实更现代、更符合工程化需求但它们的底层逻辑仍然是虚拟环境隔离。你如果已经很清楚virtualenv的能力边界再上手poetry会容易得多因为你能看懂它每一步在做什么。反过来一个连virtualenv是什么都不知道的人直接用poetry出了问题会非常难排查。所以我个人的建议是不要把这两者看作“竞争”关系。virtualenv是底层基础poetry/pipenv是上层增强。先懂底层再用上层困难会少很多。如果你已经在用virtualenv管理多个项目暂时不想折腾也完全没问题工具没有淘汰这一说只有合不合适。7. 安装与使用virtualenv过程中的常见坑与排查思路最后这一章我把这几年见过、自己踩过的坑集中列出来。这些问题大多不是virtualenv本身有bug而是使用姿势或者环境配置上的问题但梳理清楚能帮你少走很多弯路。7.1 创建虚拟环境时报“ModuleNotFoundError: No module named distutils”我在一些比较新的Linux发行版上遇到过类似情况原因是系统自带的Python里缺少distutils这个标准库组件。virtualenv在创建环境时依赖它。解决办法通过系统的包管理器安装对应的包比如Debian/Ubuntu下执行sudo apt install python3-distutils装完再创建虚拟环境就正常了。如果你的Python是源码编译安装的可以检查一下编译时是否包含了必要的依赖。7.2 激活后pip显示的还是全局路径这种情况一般是激活脚本和你当前终端的状态没配合好。激活后可以用以下命令确认当前环境which python which pip正常情况下执行结果应该指向venv目录内的路径例如/path/to/project/venv/bin/python /path/to/project/venv/bin/pip如果显示的路径不是这样有几种可能性一是你根本没激活成功注意看提示符前缀二是当前Shell的缓存问题执行hash -r刷新一下三是你的PATH被其他脚本抢占了顺序。我遇到过一种情况是conda的初始化脚本和virtualenv的激活脚本冲突conda会自动把自己的环境路径插入到最前面导致virtualenv的优先失效。解决办法就是尽量别在同一个终端里混用conda activate和virtualenv activate。7.3 Windows下激活失败提示“无法加载文件因为在此系统上禁止运行脚本”Windows PowerShell下运行Activate.ps1时如果提示这个错说明PowerShell执行策略默认禁止运行脚本。解决办法有两种一是以管理员身份打开PowerShell临时更改执行策略Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser执行完再激活。二是如果你不想动执行策略也可以用下面的命令调用cmd的激活脚本cmd /c venv\Scripts\activate.bat myscript.bat这样的用法比较绕不推荐日常使用。我建议直接把执行策略调整好一劳永逸。7.4 虚拟环境目录挪了位置python直接跑不了这个坑很经典。virtualenv创建的虚拟环境里各脚本的shebang写死了创建时的Python解释器路径。你把整个venv文件夹移动到另一个目录或者从别的机器直接拷贝过来激活虽然能成功但pip等其他命令可能因为路径对不上而报错。解决思路是环境不要跨机器拷贝。换机器就老老实实用requirements.txt重建别图省事去压缩venv目录传过去。如果是同一台机器上想把项目目录挪个位置新建虚拟环境也比修复旧的来得稳妥。7.5 虚拟环境被误删项目依赖一起消失这个坑多半是手滑不全是virtualenv的问题。我在有次清理磁盘时rm -rf点错了把一个项目的venv给删了当时那个项目没有及时生成requirements.txt恢复起来比较麻烦。后来我就定了一个规矩每次在一个环境里装完新的包顺手就执行一次pip freeze requirements.txt。养成这个习惯之后哪怕某天venv被干掉撑死五分钟就能把环境拉回来。如果你也有维护多个虚拟环境的需求建议定期跑一遍freeze把依赖快照备份好。7.6 经验技巧用别名和脚本让激活命令更顺手如果你每天要在多个虚拟环境之间切换每次敲source venv/bin/activate确实烦。我用的是给每个项目写一个activate.sh脚本的笨但有效的方法#!/bin/bash source /path/to/project/venv/bin/activate cd /path/to/project然后给脚本起个简短别名比如startmyproject这样每次只要敲一个别名自动进入虚拟环境并切换到项目目录。这个方法没有任何技术含量但它真的能让你更乐意去用虚拟环境。工具好不好用很大程度取决于它能不能融入你的肌肉记忆。8. 一点实际使用体会如果你正在被Python依赖冲突折磨或者还在犹豫“我这种小项目需不需要虚拟环境”我想说的是趁早用起来。virtualenv这东西并不复杂把它理解成“项目专属的Python运行沙箱”就够了它解决的是一个真实存在且高频发生的工程问题。实际使用过程中我的体会是virtualenv最宝贵的不是某个命令而是它带来的一个思维习惯——环境是廉价且可再生的。有了这个习惯你就不怕把一个环境折腾坏也不怕在新机器上从零搭建项目因为你知道只要有一份requirements.txt环境重建只是时间问题。它让我更敢尝试、更敢升级、更敢“破坏”背后是随时可以翻盘重来的底气。最后再补一个小技巧如果你准备把某个项目长期维护可以把“创建venv、安装依赖、启动服务”这三个步骤写成一条脚本放进项目的scripts目录。看起来是件微不足道的小事但在换电脑、换同事、交接项目的时候它带给你的顺畅感会远超这点投入。 
长河君 · 2026/10/15 17:28:04 · 阅读 1.2k Python依赖管理实战：virtualenv安装、使用与避坑指南
平时开发Python项目时最让人头疼的往往不是业务逻辑本身而是依赖管理。尤其当你同时维护着多个项目这个要Requests 2.x那个要Requests 3.x还有的项目必须锁死在Python 3.6装新库怕影响旧项目不装又无法推进新需求。我之前有段时间一直被这个问题折腾直到真正搞懂了virtualenv才算是把开发环境这块理顺了。这篇就基于我的实际使用经验把virtualenv从安装到日常使用的完整链路、里面容易踩的坑和背后的工作原理都拆开讲清楚。1. 为什么说virtualenv是Python开发的“隔离舱”很多人刚接触Python时都是直接在全局环境里pip install这在一台机器只跑一个项目的时候问题不大但一旦项目多起来依赖冲突几乎是必然的。我见过最典型的案例某公司的内部工具链依赖Django 1.11而另一个新项目需要Django 3.2两边都用全局环境结果就是装完新项目旧工具直接跑不起来报错一堆。virtualenv解决的就是这个核心矛盾——它为每一个项目创建一个独立的Python运行环境在这个环境里你可以任意安装、升级、删除第三方库而完全不影响全局环境和其他项目。我更喜欢叫它“隔离舱”因为它的作用和船舱水密隔断是一个逻辑某个舱进水了不会导致整条船沉掉。你的某个项目把环境搞坏了其他项目照样毫发无损。从技术原理上说virtualenv做的事情并不神秘。它会复制一份当前Python解释器或者你指定的某个版本的解释器到项目目录下的venv文件夹中同时建立独立的site-packages目录。当你激活这个虚拟环境时它的核心动作就是修改PATH环境变量把venv/Scripts或者venv/bin这个路径挪到最前面这样你在终端里敲python、pip实际执行到的就是虚拟环境里的那一份而不是全局的。这套机制的关键点在于解释器隔离虚拟环境里的python指向的是venv目录下的解释器不是系统路径下的那个。包管理隔离pip install安装的第三方库会写入虚拟环境自己的site-packages全局环境干干净净。无需系统权限很多服务器上你没有root权限全局pip安装会报权限错误但虚拟环境是装在自己项目目录下的不需要任何额外权限。注意virtualenv创建出的环境不是完整的Python发行版它更像是“复制了一套解释器纯净的第三方包目录”标准库依然是继承自你指定的那个Python版本的。这个理解很重要后面排查问题会用到。所以如果你是以下这几类开发者我建议你直接开始用virtualenv同时维护多个Python项目且依赖各不相同。需要在没有管理员权限的服务器上部署应用。想用一个固定版本的Python测试自己的代码在不同解释器下的表现。刚学Python不久希望从一开始就养成干净的环境管理习惯。2. 安装在开始之前virtualenv与系统Python的关系先说结论virtualenv本身就是一个普通的Python第三方库通过pip装到全局环境或者用户目录下就行。它不要求你预先创建任何虚拟环境恰恰相反它是“创建虚拟环境”的工具。安装命令非常简单但在这之前有两点需要先确认好。第一确认你的Python版本。virtualenv对Python 2.7和Python 3都有支持但如果你还在用Python 2.7要注意新版本的virtualenv可能已经不兼容了。官方是这么说的Python 2.7的支持在virtualenv 20.x早期版本中保留但后续版本已经放弃。所以如果你还在维护Python 2的老项目我建议用virtualenv20.16.6这个版本实测还算稳定。第二确认pip是否可用。现在的Python安装包一般都会自带pip但某些精简安装或者Linux系统自带的Python可能没有。你可以执行一下pip --version如果提示找不到命令可能需要先通过ensurepip或者操作系统的包管理器把pip装上。确认无误后安装virtualenvpip install virtualenv安装完成后验证一下virtualenv --version我实际操作中更推荐用python -m virtualenv这种方式来调用它而不是直接敲virtualenv命令。原因有两个一是当你系统里有多个Python版本时用python -m virtualenv能明确指定是“当前这个python解释器”在创建环境不会因为PATH里到底哪个virtualenv在前而弄得糊涂二是很多人喜欢给命令起别名结果时间长了都不知道实际调的是哪个版本。python -m virtualenv --version如果这一步能正确输出版本号说明工具已经就绪。接下来就可以创建虚拟环境了。2.1 用国内镜像源提速如果是给公司内网机器或者自己的服务器装网络情况可能不太稳定。我在境内部署时常用清华的镜像源来加速pip install virtualenv -i https://pypi.tuna.tsinghua.edu.cn/simple这里提醒一句使用镜像源的时候留意一下你所在网络环境的访问规则不同地区、不同网络能访问的源不完全一样。通常清华、阿里云这些镜像都是可用的选一个能稳定访问的即可。3. 创建虚拟环境的完整步骤与参数选择安装好后进入你的项目目录执行如下命令创建虚拟环境cd /path/to/your/project python -m virtualenv venv这条命令会创建一个名为venv的文件夹里面就是一套独立的Python环境。这个文件夹的名称可以自己定不过我建议统一用venv、.venv或者env后面配置.gitignore和IDE识别都会省心很多。创建过程会有输出信息大意是“创建了Python X环境的虚拟环境”之类。如果你用的是virtualenv 20.x还会提示你创建的虚拟环境里包含pip、setuptools等核心工具。这就意味着你不需要再手动给虚拟环境装pip——它已经自带了。创建完以后目录结构大致是venv/ ├── bin/ # Linux/macOS下的可执行文件python、pip都在这里 │ ├── activate │ ├── python │ ├── pip │ └── ... ├── include/ ├── lib/ # 实际存放第三方包的site-packages所在目录 │ └── python3.x/ └── pyvenv.cfg # 配置文件记录了指向哪个基础Python版本Windows下略有不同Scripts目录代替了binactivate脚本在Scripts里。3.1 常用参数详解--python、--system-site-packages、--no-pipvirtualenv创建环境时支持不少参数我只挑几个日常真正用得上、面向实战场景的说一下。--python或-p指定用哪个Python解释器来创建环境。这在你有多个Python版本时会非常有用。比如你系统里同时装了Python 3.8和Python 3.11但项目要求3.8可以这样指定python -m virtualenv -p python3.8 venv甚至可以直接指向解释器的具体路径python -m virtualenv -p /usr/local/bin/python3.8 venv指定路径的方式更精确避免系统里存在多个同名python3.8时搞错。Windows下路径类似C:\Python38\python.exe。--system-site-packages默认情况下虚拟环境是看不到全局环境里已安装的第三方包的。加上这个参数后虚拟环境会“继承”全局site-packages里的所有包。这个参数有时候很实用——例如你全局里已经装好了一个体积很大的库而项目又正好需要它为了省磁盘空间和安装时间可以这样隔离但共享。但我要提醒一下这个参数也容易引入隐蔽的问题。因为虚拟环境里一旦激活了这个选项你在安装新包时它可能和全局的旧版本产生冲突而这种冲突还不像完全隔离那样好查。所以我个人习惯是除非有明确理由否则不用这个参数。绝大多数情况下我们需要的是彻底隔离。--no-pip、--no-setuptools创建出来的虚拟环境不自带pip或setuptools。这种一般出现在你想做一个最最干净的环境然后用get-pip.py或者自己后面手动装工具的场景。普通情况下不需要默认带上pip才是最常见的做法。3.2 激活与退出看似简单其实藏着一个关键点创建完虚拟环境后你要“进入”这个环境才能使用它。进入的动作叫激活activate。Linux/macOS下执行source venv/bin/activateWindows命令行下执行venv\Scripts\activate.batWindows PowerShell下执行venv\Scripts\Activate.ps1激活成功后命令行提示符前面会出现一个(venv)前缀例如(venv) userhostname:/path/to/project$看到这个前缀就说明当前终端会话已经处于虚拟环境之中。此时你敲python、pip、pytest等所有命令跑的都是这个虚拟环境里的那一份。退出虚拟环境只需要执行deactivate命令敲完(venv)前缀消失就回到了全局环境。这里有个关键点很多人没意识到激活只是改变了当前终端的PATH环境变量它不影响其他终端窗口也不会改变你项目的任何文件。也就是说你开一个新的终端窗口想用虚拟环境的话得在新窗口里重新执行一遍激活命令。这个特性在日常使用中要记牢不然就容易出现“明明刚才还能运行换个窗口就不行了”的困惑。4. 日常使用virtualenv最绕不开的几个操作创建和激活只是第一步真正实用的是把虚拟环境融入日常开发流程。我把平时最常用到的操作整理出来这些动作我几乎每个项目都会用到。4.1 用pip freeze锁定依赖配合requirements.txt实现环境复现当你在这个虚拟环境里安装好了项目所需的所有第三方库可以用一条命令把当前环境里所有的包连同版本号导出到一个文件pip freeze requirements.txt生成的requirements.txt长这样Django3.2.19 requests2.31.0 gunicorn20.1.0这份文件就是项目的“依赖快照”。换一台机器、换一个同事的电脑或者部署到服务器上只需要pip install -r requirements.txt就能把一模一样的依赖环境重建出来。这意味着你根本不需要把venv这个大文件夹拷给别人只要一个几十行的文本文件就能让环境在任何机器上重现。我自己的习惯是凡是项目往仓库里提交requirements.txt一定要跟着提交。venv目录则加入.gitignore绝对不提交。一个典型的.gitignore片段长这样venv/ .venv/ __pycache__/ *.pyc4.2 升级virtualenv本身与虚拟环境的关系virtualenv这个工具本身升级了已经创建好的虚拟环境并不会自动跟着升级。virtualenv的作用只是“创建”创建完成后虚拟环境就自成一体了。所以如果你看到新版本virtualenv发布了别急着去前提下已存在的环境做什么操作。要升级的只是你拿来创建虚拟环境的那个工具而不是某个具体的虚拟环境。想用新版virtualenv创建环境重新创建即可旧的项目继续用旧环境没有任何问题。4.3 在PyCharm或VS Code里指定虚拟环境现代IDE都支持直接使用虚拟环境不需要每次都在终端里激活。以PyCharm为例打开项目设置里的Python Interpreter选择“Existing Environment”把路径指到venv/bin/python # Linux/macOS venv\Scripts\python.exe # Windows之后PyCharm的终端、运行按钮都会自动使用这个虚拟环境的解释器。VS Code则是通过命令面板里“Python: Select Interpreter”选择对应路径。这样下来日常写代码就完全不用手动激活了IDE帮你处理好了一切。4.4 删除与重建虚拟环境坏了怎么办虚拟环境里的包装乱了、版本冲突解不开了或者Python升级后环境出现莫名其妙的问题最干脆的解决办法就是删掉重来deactivate rm -rf venv python -m virtualenv venv pip install -r requirements.txt整个过程不会超过两分钟而且有requirements.txt保障重建后依赖完全一致。这就是虚拟环境最大的优势之一——环境是“可再生资源”不值得你去修复一个破损的环境坏了大不了重建。5. 多版本Python场景下virtualenv的配合策略上面提到过-p参数可以指定Python版本。这一节展开讲讲项目里需要多个Python版本时怎么搭配virtualenv最顺手。先说一个常见场景你可能需要在Python 3.8上验证代码兼容性同时又在Python 3.11上开发新功能。如果你直接用virtualenv可以创建两个不同名字的环境python -m virtualenv -p python3.8 venv38 python -m virtualenv -p python3.11 venv311需要用哪个环境就激活哪个。这样两个环境的第三方依赖可以完全分开互不干扰。不过如果你频繁要切换不同版本的Python我建议再配一个工具pyenv。pyenv负责管理“安装哪些版本的Python”virtualenv则负责“基于某个版本创建隔离环境”。两者的分工可以说非常清晰pyenv决定你的项目用哪个Python解释器virtualenv决定那个解释器下的第三方包装在哪里、和全局环境怎么隔离我的习惯是先通过pyenv安装好需要的Python版本然后在项目里用virtualenv基于对应版本创建环境。在旧版本Python上测试时这个组合非常可靠测试完一点痕迹都不留在全局。还可以简单提一下conda。如果你本来就用conda管理环境和包那virtualenv在conda体系里其实是多余的因为conda自带环境管理。但对于不用conda的普通pip用户来说virtualenv依然是经典且通用的选择。这两条路径没有绝对的高下之分只是生态偏好不同而已。6. virtualenv、venv、virtualenvwrapper、pipenv、poetry的取舍标题是“virtualenv的安装”但其实很多新手会把这一堆名词都搞混。我自己刚开始也花了一段时间才理清楚这里就一次性说透。6.1 virtualenv与内置venv的关系Python 3.3以后标准库中新增了venv模块它提供了类似virtualenv的虚拟环境能力。也就是说如果你用的Python版本是3.3及以上理论上可以不安装virtualenv直接用python -m venv venv那为什么还要用virtualenv最核心的区别是两者创建的“环境级别”有别venv是标准库自带的使用方便但对于Python老版本2.x和3.3以下不支持而virtualenv是第三方库可以支持更老版本的Python而且提供了额外的灵活性和跨版本支持。virtualenv还支持通过--system-site-packages等参数做更细粒度的配置以及提供了更完善的全局工具整合能力。对于现代Python项目3.6以上说实话只用venv也完全够用。但你如果需要在同一台机器上管理多个老版本Python项目virtualenv仍然是更方便的选择。6.2 virtualenvwrapper带来的效率提升virtualenv本身有个小小的不便每次要用环境都得手动去找路径然后source。项目多了效率就下来了。virtualenvwrapper就是解决这个问题的pip install virtualenvwrapper安装后通过配置几条环境变量WORKON_HOME等你就能用workon project1命令直接激活对应的虚拟环境不用记路径、不用手动source。还有lsvirtualenv、rmvirtualenv、cpvirtualenv等一系列管理命令。这套工具在Linux服务器管理多个项目时效率提升非常明显。我见过不少人直接在.bashrc或.zshrc里写死一处配置然后所有的项目环境都通过virtualenvwrapper来管理体验很流畅。Windows上则对应的是virtualenvwrapper-win。6.3 pipenv与poetry更现代但更需要理解底层pipenv和poetry是virtualenv和pip的上层封装它们不只是管理虚拟环境还把依赖解析、锁定、打包等一并纳入。比如poetry会用pyproject.toml记录依赖声明用poetry.lock锁定精确版本。这些工具本身确实更现代、更符合工程化需求但它们的底层逻辑仍然是虚拟环境隔离。你如果已经很清楚virtualenv的能力边界再上手poetry会容易得多因为你能看懂它每一步在做什么。反过来一个连virtualenv是什么都不知道的人直接用poetry出了问题会非常难排查。所以我个人的建议是不要把这两者看作“竞争”关系。virtualenv是底层基础poetry/pipenv是上层增强。先懂底层再用上层困难会少很多。如果你已经在用virtualenv管理多个项目暂时不想折腾也完全没问题工具没有淘汰这一说只有合不合适。7. 安装与使用virtualenv过程中的常见坑与排查思路最后这一章我把这几年见过、自己踩过的坑集中列出来。这些问题大多不是virtualenv本身有bug而是使用姿势或者环境配置上的问题但梳理清楚能帮你少走很多弯路。7.1 创建虚拟环境时报“ModuleNotFoundError: No module named distutils”我在一些比较新的Linux发行版上遇到过类似情况原因是系统自带的Python里缺少distutils这个标准库组件。virtualenv在创建环境时依赖它。解决办法通过系统的包管理器安装对应的包比如Debian/Ubuntu下执行sudo apt install python3-distutils装完再创建虚拟环境就正常了。如果你的Python是源码编译安装的可以检查一下编译时是否包含了必要的依赖。7.2 激活后pip显示的还是全局路径这种情况一般是激活脚本和你当前终端的状态没配合好。激活后可以用以下命令确认当前环境which python which pip正常情况下执行结果应该指向venv目录内的路径例如/path/to/project/venv/bin/python /path/to/project/venv/bin/pip如果显示的路径不是这样有几种可能性一是你根本没激活成功注意看提示符前缀二是当前Shell的缓存问题执行hash -r刷新一下三是你的PATH被其他脚本抢占了顺序。我遇到过一种情况是conda的初始化脚本和virtualenv的激活脚本冲突conda会自动把自己的环境路径插入到最前面导致virtualenv的优先失效。解决办法就是尽量别在同一个终端里混用conda activate和virtualenv activate。7.3 Windows下激活失败提示“无法加载文件因为在此系统上禁止运行脚本”Windows PowerShell下运行Activate.ps1时如果提示这个错说明PowerShell执行策略默认禁止运行脚本。解决办法有两种一是以管理员身份打开PowerShell临时更改执行策略Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser执行完再激活。二是如果你不想动执行策略也可以用下面的命令调用cmd的激活脚本cmd /c venv\Scripts\activate.bat myscript.bat这样的用法比较绕不推荐日常使用。我建议直接把执行策略调整好一劳永逸。7.4 虚拟环境目录挪了位置python直接跑不了这个坑很经典。virtualenv创建的虚拟环境里各脚本的shebang写死了创建时的Python解释器路径。你把整个venv文件夹移动到另一个目录或者从别的机器直接拷贝过来激活虽然能成功但pip等其他命令可能因为路径对不上而报错。解决思路是环境不要跨机器拷贝。换机器就老老实实用requirements.txt重建别图省事去压缩venv目录传过去。如果是同一台机器上想把项目目录挪个位置新建虚拟环境也比修复旧的来得稳妥。7.5 虚拟环境被误删项目依赖一起消失这个坑多半是手滑不全是virtualenv的问题。我在有次清理磁盘时rm -rf点错了把一个项目的venv给删了当时那个项目没有及时生成requirements.txt恢复起来比较麻烦。后来我就定了一个规矩每次在一个环境里装完新的包顺手就执行一次pip freeze requirements.txt。养成这个习惯之后哪怕某天venv被干掉撑死五分钟就能把环境拉回来。如果你也有维护多个虚拟环境的需求建议定期跑一遍freeze把依赖快照备份好。7.6 经验技巧用别名和脚本让激活命令更顺手如果你每天要在多个虚拟环境之间切换每次敲source venv/bin/activate确实烦。我用的是给每个项目写一个activate.sh脚本的笨但有效的方法#!/bin/bash source /path/to/project/venv/bin/activate cd /path/to/project然后给脚本起个简短别名比如startmyproject这样每次只要敲一个别名自动进入虚拟环境并切换到项目目录。这个方法没有任何技术含量但它真的能让你更乐意去用虚拟环境。工具好不好用很大程度取决于它能不能融入你的肌肉记忆。8. 一点实际使用体会如果你正在被Python依赖冲突折磨或者还在犹豫“我这种小项目需不需要虚拟环境”我想说的是趁早用起来。virtualenv这东西并不复杂把它理解成“项目专属的Python运行沙箱”就够了它解决的是一个真实存在且高频发生的工程问题。实际使用过程中我的体会是virtualenv最宝贵的不是某个命令而是它带来的一个思维习惯——环境是廉价且可再生的。有了这个习惯你就不怕把一个环境折腾坏也不怕在新机器上从零搭建项目因为你知道只要有一份requirements.txt环境重建只是时间问题。它让我更敢尝试、更敢升级、更敢“破坏”背后是随时可以翻盘重来的底气。最后再补一个小技巧如果你准备把某个项目长期维护可以把“创建venv、安装依赖、启动服务”这三个步骤写成一条脚本放进项目的scripts目录。看起来是件微不足道的小事但在换电脑、换同事、交接项目的时候它带给你的顺畅感会远超这点投入。