Python怎么用自带的venv模块搭建虚拟环境?

阿麦
阿麦
发布时间:2026-11-22| 6人浏览过
原创

详细讲解如何使用Python 3内置的venv标准库创建、激活、使用与退出独立的虚拟环境,深入剖析其底层目录与隔离机制,并提供Windows与macOS/Linux跨平台操作及常见排错指南。

Python 3.3 及更高版本已内置标准库 venv,不需要借助任何第三方工具即可创建轻量、完全独立的虚拟运行环境。只需在目标项目路径下执行 python -m venv .venv,系统就会生成专属的解释器引导文件与依赖库目录。激活该环境后,所有通过 pip 安装的第三方包均会被隔离在该目录下,彻底规避项目间库版本冲突与系统全局环境污染。本文将按照准备检查、核心操作四步法、底层隔离机制及常见故障排查的完整流程展开详解。
Python怎么用自带的venv模块搭建虚拟环境?
图 1:Python 全局依赖冲突与 venv 独立环境隔离模型对比

一、搭建前的必要准备与命令语法

在开始搭建虚拟环境之前,需要确认当前计算机已正确安装 Python 3 环境。在终端(Terminal)或命令提示符中执行以下命令查看版本:

python --version
# 如果你的操作系统默认 python 指向 Python 2,请改用 python3 命令
python3 --version
示例输出
Python 3.11.8

只要输出的主版本号大于或等于 3.3,就说明系统已具备 venv 模块。venv 是 Python 标准库的内置组件,创建虚拟环境的标准语法格式如下:

python -m venv <环境保存路径>

其中各参数的具体含义为:

  • python:调用当前系统的 Python 解释器主程序。
  • -m venv:表示以脚本方式运行标准库内置的 venv 模块。
  • <环境保存路径>:虚拟环境的目录名称。业界推荐在项目根目录下使用 .venv(带有前导点,便于在类 Unix 系统中自动隐藏)或 venv 作为名称。
Linux 系统特别提示:在 Debian 或 Ubuntu 发行版中,系统的精简包管理策略将 venv 拆分成了单独的软件包。若执行时提示缺少 ensurepip 或找不到模块,需先在终端运行 sudo apt install python3-venv 完成补全。

二、标准四步法:创建、激活、使用与退出

使用 venv 管理虚拟环境的完整生命周期可归纳为清晰的四个步骤:先在目标项目根目录创建环境文件夹,然后执行终端脚本将其激活,接着使用隔离的解释器与 pip 安装库,开发结束后退出环境。

Python怎么用自带的venv模块搭建虚拟环境?
图 2:从创建、激活、使用到退出的全流程操作模型

第 1 步:创建虚拟环境

在终端中进入项目的工作目录,执行创建指令:

# 进入你的项目根目录
cd /path/to/my_project

# 创建名为 .venv 的虚拟环境文件夹
python -m venv .venv

执行该命令后终端通常不会产生任何提示文本,但项目目录下会新增一个 .venv 文件夹,里面包含了该环境专属的配置文件与目录结构。

第 2 步:激活虚拟环境

激活虚拟环境的作用是修改当前终端会话的环境变量 PATH,让系统在执行 python 和 pip 时优先调用该虚拟目录中的解释器。不同操作系统与终端工具所使用的激活脚本略有不同:

操作系统 / 终端类型 激活命令 脚本路径
macOS / Linux (bash/zsh) source .venv/bin/activate .venv/bin/activate
Windows (PowerShell) .venv\Scripts\Activate.ps1 .venv\Scripts\Activate.ps1
Windows (CMD 命令提示符) .venv\Scripts\activate.bat .venv\Scripts\activate.bat
Windows (Git Bash) source .venv/Scripts/activate .venv/Scripts/activate

成功激活后,终端提示符最左侧会出现形如 (.venv) 的前缀提示:

终端激活成功示例
(.venv) user@host:~/my_project$

第 3 步:验证与安装第三方依赖

在激活状态下,可以通过查询当前 python 可执行文件的绝对路径,验证是否已切换至虚拟环境:

# Linux / macOS
which python

# Windows
where python
示例输出 (macOS / Linux)
/Users/username/my_project/.venv/bin/python

此时使用 pip install 安装所需的任何扩展库,所有文件都只会被下载写入到当前 .venv 的内部目录中:

# 安装项目所需的 requests 模块
pip install requests

第 4 步:退出虚拟环境

当当前项目的开发或测试工作完成时,无需删除文件夹,只需在终端中执行内置函数:

deactivate

命令执行后,终端提示符前缀中的 (.venv) 会立即消失,终端的 PATH 环境变量自动恢复到运行该命令前的全局状态。

三、虚拟环境的内部结构与工作机制

许多初学者误以为 venv 会把完整的 Python 解释器连同庞大的标准库全部复制一份,造成磁盘空间浪费。实际上 venv 的设计极其轻量,其生成的核心目录结构与文件职责如下:

Python怎么用自带的venv模块搭建虚拟环境?
图 3:venv 内部目录结构与各关键文件分工示意

在 .venv 根目录下的 pyvenv.cfg 文件是实现环境隔离的关键。打开该文件,其内容一般如下:

home = /usr/local/bin
include-system-site-packages = false
version = 3.11.8
executable = /usr/local/bin/python3.11
command = /usr/local/bin/python3 -m venv /Users/username/my_project/.venv

当虚拟环境下的 python 启动时,它会首先向上查找同级或父级目录中的 pyvenv.cfg:

  1. 若读取到 include-system-site-packages = false,解释器在导入模块时将自动屏蔽操作系统全局的 site-packages 目录,只检索本虚拟环境的 site-packages。
  2. 解释器所需的内置基础标准库(如 sys、os、json、math)并不会重复复制到 .venv 中,而是直接通过 home 属性回溯到全局 Python 安装路径读取。这种机制既保障了环境的纯净与隔离,又把单个虚拟环境的初始占用体积控制在数兆字节(MB)以内。

四、团队协作与依赖清单管理

虚拟环境中包含大量与当前计算机平台绑定的绝对路径与可执行二进制文件,因此切勿将 .venv 文件夹提交到 Git 等代码版本仓库中。

在项目根目录的 .gitignore 文件中必须加入虚拟环境的过滤规则:

# 忽略虚拟环境文件夹
.venv/
venv/
ENV/

为了让其他协作开发者或部署服务器能够一键还原相同的运行环境,规范的做法是通过 requirements.txt 文件记录依赖清单:

# 1. 在当前激活的虚拟环境中导出已安装的库与具体版本号
pip freeze > requirements.txt

# 2. 团队成员拉取代码后,在全新的虚拟环境中一键批量安装
pip install -r requirements.txt

五、常见问题排查与解决方法

在实际搭建和使用 venv 的过程中,初学者常会遇到终端报错或依赖没有装入环境的情况,以下是三个最具代表性的问题及针对性排查思路:

Python怎么用自带的venv模块搭建虚拟环境?
图 4:常见报错定位、根因分析与针对性解决手段

1. Windows PowerShell 报错“在此系统上禁止运行脚本”

在 Windows 系统的 PowerShell 中执行 .venv\Scripts\Activate.ps1 时,常出现如下错误提示:

PowerShell 错误输出
.venv\Scripts\Activate.ps1 : 无法加载文件,因为在此系统上禁止运行脚本。有关详细信息,请参阅 https:/go.microsoft.com/fwlink/?LinkID=135170 中的 about_Execution_Policies。

原因分析:Windows 默认将当前用户的脚本执行策略(Execution Policy)设定为 Restricted,该策略会拦截一切未签名的本地脚本运行。

解决办法:在当前 PowerShell 窗口中运行以下命令,将当前用户的策略放宽为 RemoteSigned(仅针对当前用户生效,无需管理员提权):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

设置完成后重新运行 .venv\Scripts\Activate.ps1 即可成功激活。

2. Linux / Ubuntu 提示“ensurepip is not available”

在基于 Debian 或 Ubuntu 的服务器环境中执行 python3 -m venv .venv 时,可能会中断并报错:

Linux 错误输出
The virtual environment was not created successfully because ensurepip is not available. On Debian/Ubuntu systems, you need to install the python3-venv package...

原因分析:这是由于操作系统软件源将 Python 核心与虚拟环境标准包分离造成的。

解决办法:更新包列表并安装对应版本的扩展组件:

sudo apt update
sudo apt install python3-venv

3. 激活后 pip 依然把包安装到了全局

有时在终端中虽然执行了激活命令,但运行 pip install 后通过 pip list 发现新安装的包并不在 .venv/lib/site-packages 下。

原因分析:在 Linux/macOS 中,如果使用 sh .venv/bin/activate 或 ./.venv/bin/activate 执行脚本,脚本会在独立的子进程中运行,子进程退出后当前父终端会话的 PATH 环境变量并未改变,导致 pip 依然指向全局系统路径。

解决办法与安全实践:在类 Unix 终端中务必使用 source 命令激活:

source .venv/bin/activate

此外,最健壮的包管理调用方式是始终使用 python -m pip install <包名>,这样能够绝对确保由当前被调用的 Python 解释器直接引导其配对的 pip 模块,完全避免 PATH 优先级错乱的问题。

六、全平台常用操作命令速查卡

为了便于日常开发随时翻阅,最后将 Windows、macOS 与 Linux 平台下围绕 venv 的核心操作命令总结归纳如下:

Python怎么用自带的venv模块搭建虚拟环境?
图 5:Python venv 跨平台核心操作命令与生命周期对照速查卡

综上所述,Python 自带的 venv 模块无需任何第三方网络依赖即可快速搭建稳定轻量的独立虚拟环境。在每个项目开发之初,通过规范化的四步流程建立专属运行空间,是编写可维护、可复现 Python 工程代码的基础习惯。

相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。