1. 项目概述为什么我们需要虚拟环境在Ubuntu上折腾项目尤其是Python项目相信不少朋友都踩过同一个坑系统里装了一堆不同版本的库A项目需要numpy1.21B项目却要求numpy1.24最后版本冲突搞得焦头烂额甚至把系统自带的Python环境搞崩。虚拟环境Virtual Environment就是为解决这个问题而生的“隔离舱”。它允许你为每个项目创建一个独立的Python运行环境在这个环境里安装的包、配置的路径都只对当前项目生效不同项目之间互不干扰。这就像给每个项目分配了一个专属的、干净的房间你在房间里怎么折腾都不会影响到客厅系统环境和其他房间其他项目。对于在Ubuntu上进行开发、数据科学、机器学习或者运维部署的朋友来说掌握虚拟环境的创建和使用是必备技能。无论是从GitHub拉取一个开源项目来运行还是自己开发一个应用第一步往往就是搭建一个专属的虚拟环境。这不仅能保证项目依赖的纯净和可复现性也极大地简化了后续的部署和迁移流程。今天我就以一个资深开发者的视角带你从零开始在Ubuntu上完成创建虚拟环境、安装项目依赖、并成功运行项目的完整闭环。我们会聚焦于最通用、最轻量的venv模块同时也会对比介绍conda等工具让你知其然更知其所以然。2. 核心工具选型venv vs conda vs 其他在Ubuntu上创建Python虚拟环境主流工具有两个Python标准库自带的venv和第三方发行版Anaconda/Miniconda附带的conda。选择哪个取决于你的具体场景。2.1 Python venv轻量、标准、推荐venv是Python 3.3版本内置的模块无需额外安装只要你的Python3是从官方源安装的。它的最大优点是轻量和标准。创建的环境只包含最基本的Python解释器和pip非常干净。它通过修改环境变量PATH将当前环境的python和pip命令指向隔离目录从而实现环境隔离。适用场景纯粹的Python项目开发。项目依赖主要通过pip从PyPI安装。追求环境最小化部署到生产服务器。你希望使用系统包管理器如apt管理非Python依赖如数据库客户端、系统库。注意venv创建的环境是“软链接”到系统Python解释器的它并不复制一份完整的Python。这意味着如果你升级了系统的Python虚拟环境可能受到影响。最佳实践是为每个项目固定Python版本。2.2 Conda跨语言、强大的包管理Conda本身是一个独立的开源包管理和环境管理系统它不仅可以管理Python包还能管理R、C/C、Java等多种语言的包甚至能安装非Python的二进制工具。它通过创建完全独立的目录树来实现环境隔离环境之间更加彻底。适用场景数据科学、机器学习项目经常需要复杂的数据栈如NumPy, SciPy, Pandas, TensorFlow, PyTorch。项目依赖包含大量需要编译的C扩展库conda提供了预编译好的二进制包避免复杂的编译环境配置。需要方便地安装和管理非Python依赖比如ffmpeg、cuda工具包等。在Windows系统上conda是管理科学计算环境的利器。一个常见问题的解答在搜索热词中看到“conda创建新虚拟环境显示the channel is not accessible”。这通常是因为.condarc配置文件中的镜像源地址失效或网络问题。解决方法通常是更换为国内的镜像源如清华、中科大源或者检查网络连接。我们的选择对于大多数通用的Python Web开发、脚本编写、自动化任务venv因其简单、标准而足够好用。本文将主要使用venv进行演示并在关键步骤指出与conda的异同。3. 实操准备Ubuntu系统与Python基础配置在开始创建环境之前我们需要确保系统处于一个良好的起点。这里假设你使用的是Ubuntu 22.04 LTS或20.04 LTS这是目前最稳定的两个长期支持版本。3.1 确保Python3与pip可用首先打开你的终端CtrlAltT。Ubuntu 22.04默认已经安装了Python 3.10。我们可以通过以下命令确认python3 --version pip3 --version如果pip3提示未安装可以使用Ubuntu的包管理器apt来安装sudo apt update sudo apt install python3-pip -y实操心得始终使用python3和pip3命令来明确指定使用的是Python 3。虽然有些教程会教你通过update-alternatives将python命令链接到python3但在生产服务器或需要严格版本控制的场景下保持明确性可以避免很多潜在的混淆和错误。3.2 升级pip至最新版本系统自带的pip版本可能较旧。使用最新版的pip可以确保包安装过程更稳定支持更多新特性。pip3 install --upgrade pip升级后可以通过pip --version注意升级后通常可以直接使用pip命令来确认版本。4. 核心环节一使用venv创建虚拟环境现在进入我们项目的核心目录。假设你的项目名为my_awesome_project位于家目录下。cd ~ mkdir my_awesome_project cd my_awesome_project4.1 创建虚拟环境在当前目录下执行创建虚拟环境的命令python3 -m venv venv这条命令的含义是调用Python 3的venv模块在当前目录.下创建一个名为venv的虚拟环境目录。你也可以取其他名字比如.venv、env等但venv是社区常见的约定。命令执行后你会看到当前目录下多了一个名为venv的文件夹。它的内部结构大致如下venv/ ├── bin/ # 存放可执行文件如python, pip, activate脚本 ├── include/ # C头文件 ├── lib/ # 所有安装的Python包都在这里的site-packages下 └── pyvenv.cfg # 环境配置文件4.2 激活虚拟环境创建环境后它只是一个孤立的目录。我们需要“激活”它让当前的终端会话知道后续所有的python和pip命令都应该指向这个隔离环境。source venv/bin/activate激活成功后你的命令行提示符PS1通常会发生变化最前面会显示虚拟环境的名称(venv)如下所示(venv) userhost:~/my_awesome_project$现在你可以验证一下Python和pip的路径which python which pip输出应该指向~/my_awesome_project/venv/bin/下的文件而不是/usr/bin/。重要注意事项激活操作只对当前这个终端标签页或会话有效。如果你新开一个终端标签页需要重新进入项目目录并再次执行source venv/bin/activate。当你完成工作想退出虚拟环境时只需输入命令deactivate提示符就会恢复原样。4.3 使用conda创建环境备选方案如果你选择使用conda步骤有所不同。首先你需要安装Miniconda或Anaconda。以Miniconda为例从官网下载安装脚本后bash Miniconda3-latest-Linux-x86_64.sh # 安装后重启终端或运行 source ~/.bashrc创建环境的命令是conda create --name my_env python3.9 # 创建一个名为my_envPython版本为3.9的环境 conda activate my_env # 激活环境 conda deactivate # 退出环境conda的环境默认安装在~/miniconda3/envs/目录下与项目目录分离。这对于管理多个使用相同Python版本但不同包的项目可能不够直观但便于集中管理所有环境。5. 核心环节二在虚拟环境中安装项目依赖环境激活后我们就进入了这个干净的“房间”。接下来就要根据项目的需要在这个房间里布置家具——安装Python包。5.1 理解依赖管理文件requirements.txt一个规范的项目通常会包含一个requirements.txt文件它列出了项目运行所需的所有第三方包及其精确版本。例如Django4.2.7 requests2.28.0,3.0.0 pandas numpy1.24.3指定精确版本。指定最低版本。指定最高版本不包含。只写包名安装最新稳定版。5.2 安装依赖假设你的项目目录下已经有requirements.txt文件安装命令非常简单(venv) pip install -r requirements.txtpip会自动从PyPIPython包索引下载并安装所有列出的包及其依赖项。安装过程中你会看到大量的下载和安装日志。如果没有requirements.txt文件怎么办手动安装如果你知道项目需要哪些包可以逐个安装pip install django requests pandas。生成requirements.txt如果你是在一个已有的、能运行的项目中但缺少依赖声明文件可以在虚拟环境中安装好所有必需的包后运行以下命令生成它(venv) pip freeze requirements.txtpip freeze会列出当前环境中所有已安装的包及其版本输出重定向到文件就生成了requirements.txt。务必在虚拟环境中执行此操作否则会导出系统全局的所有包5.3 使用国内镜像源加速下载直接从PyPI下载可能会很慢。我们可以使用国内的镜像源来大幅提升下载速度。在安装时通过-i参数指定镜像源(venv) pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple常用的国内镜像源有清华https://pypi.tuna.tsinghua.edu.cn/simple阿里云https://mirrors.aliyun.com/pypi/simple/中国科技大学https://pypi.mirrors.ustc.edu.cn/simple/如果你想设置为默认可以创建或修改~/.pip/pip.conf文件Linux/macOS或%APPDATA%\pip\pip.iniWindows[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn5.4 安装特定版本的Python包有时项目需要特定版本的包或者你需要降级/升级某个包。使用pip install指定版本即可(venv) pip install pandas1.5.3 # 安装精确版本 (venv) pip install --upgrade pandas # 升级到最新版本 (venv) pip install pandas~1.5.0 # 安装兼容版本相当于1.5.0, 1.6.06. 核心环节三运行你的项目依赖安装完毕虚拟环境已经准备就绪是时候让项目跑起来了。运行项目的具体命令因项目类型而异。6.1 运行Python脚本对于单个的Python脚本文件例如main.py或app.py直接使用虚拟环境中的Python解释器运行即可(venv) python main.py6.2 运行Django项目典型的Django项目会有一个manage.py文件作为入口。首先确保已安装Django通常在requirements.txt中已包含。应用数据库迁移如果项目使用数据库(venv) python manage.py migrate创建超级用户如果需要后台管理(venv) python manage.py createsuperuser启动开发服务器(venv) python manage.py runserver默认情况下服务器会运行在http://127.0.0.1:8000。在浏览器中访问这个地址你应该能看到Django的欢迎页面或你的应用。6.3 运行Flask项目Flask项目通常有一个主应用文件例如app.py或run.py。设置Flask应用入口如果需要(venv) export FLASK_APPapp.py # 对于Windows CMD: set FLASK_APPapp.py # 对于Windows PowerShell: $env:FLASK_APPapp.py启动开发服务器(venv) flask run # 或者 python app.py (如果app.py中直接调用了app.run())服务器通常运行在http://127.0.0.1:5000。6.4 运行从GitHub克隆的项目这是搜索热词中的高频需求“github上的项目怎么运行”、“从github下载项目并运行”。通用步骤如下克隆项目git clone https://github.com/username/repo.git cd repo查看项目说明务必首先阅读README.md文件作者通常会在里面写明安装和运行步骤、依赖的Python版本、是否需要特殊配置等。创建并激活虚拟环境如前所述。安装依赖按照README.md的指示可能是pip install -r requirements.txt也可能是pip install -e .以可编辑模式安装当前目录的包或使用poetry/pipenv等更现代的依赖管理工具。环境变量与配置很多项目需要配置环境变量如数据库连接字符串、API密钥。通常会有.env.example或config.example.py文件你需要复制一份并填入自己的配置。初始化数据库对于Web项目可能需要运行迁移脚本。运行项目根据README.md的启动命令执行。7. 虚拟环境的管理与维护虚拟环境不是创建一次就一劳永逸的我们需要知道如何管理它们。7.1 查看已安装的包(venv) pip list # 列出所有已安装的包及其版本 (venv) pip show package_name # 查看某个特定包的详细信息7.2 更新包更新所有包到符合版本约束的最新版谨慎操作可能破坏兼容性(venv) pip list --outdated # 先查看哪些包有更新 (venv) pip install --upgrade package_name # 更新单个包更安全的方式是定期根据更新的requirements.txt重新安装。7.3 卸载包(venv) pip uninstall package_name7.4 删除虚拟环境当你确定某个项目环境不再需要时直接删除其目录即可。首先确保你已经退出了该虚拟环境deactivate。deactivate # 如果环境处于激活状态先退出 rm -rf venv/ # 删除名为venv的虚拟环境目录对于conda环境使用conda remove --name my_env --all。7.5 虚拟环境的迁移与复现虚拟环境本身venv文件夹不建议直接复制到其他机器因为其中包含的路径可能是硬编码的。正确的做法是在源环境中生成精确的依赖列表pip freeze requirements.txt。将项目代码和requirements.txt文件传到新机器。在新机器上创建新的虚拟环境并运行pip install -r requirements.txt。这保证了环境的高度可复现性。对于更复杂的依赖和环境管理可以考虑使用Docker容器化技术。8. 常见问题与排查技巧实录在实际操作中你几乎一定会遇到一些问题。下面是我总结的一些高频问题及其解决方案。8.1 创建虚拟环境失败问题Command python3 not found或The virtual environment was not created successfully...排查确认Python3已安装python3 --version。确保安装了python3-venv包某些最小化安装的Ubuntu可能没有sudo apt install python3-venv。检查目标目录的写入权限。8.2 激活脚本执行报错问题source venv/bin/activate后提示Permission denied或脚本错误。排查检查激活脚本是否存在ls -la venv/bin/activate。可能是文件格式问题如在Windows创建在Linux使用。可以尝试用dos2unix工具转换dos2unix venv/bin/activate。确保你使用的是bash或zsh等兼容shell而不是fish或csh它们有自己对应的激活脚本位于venv/bin/activate.fish。8.3 安装包时速度慢或超时问题pip install卡在下载阶段或报超时错误。解决首要方案使用国内镜像源如前文所述。增加超时时间pip install --default-timeout100 package_name。检查网络连接特别是如果使用了代理需要为pip配置代理pip install --proxyhttp://user:passproxy-server:port package_name。8.4 包版本冲突问题pip在安装时提示无法满足所有包的版本要求例如Cannot install package-a1.0 because package-b requires package-a2.0。解决这是依赖管理的核心难题。首先尝试安装主要的核心包如Django, Flask让pip自动协调依赖。如果不行查看错误信息尝试手动安装一个兼容的版本组合。有时需要稍微降低或提高某个核心包的版本。使用pip check命令来检查已安装包之间的依赖兼容性。考虑使用更先进的依赖解析工具如pip-tools(pip-compile/pip-sync) 或poetry。8.5 运行项目时提示模块未找到ModuleNotFoundError问题python app.py报错ModuleNotFoundError: No module named xxx。排查首先确认虚拟环境是否已激活这是最常见的原因。检查命令行提示符是否有(venv)前缀。确认该模块是否已安装pip list | grep xxx。如果模块已安装但依然报错可能是Python路径问题。确保你的项目目录结构正确或者尝试使用PYTHONPATH环境变量PYTHONPATH/path/to/your/project python app.py。8.6 Conda环境相关错误问题conda create失败提示The channel is not accessible或PackagesNotFoundError。解决配置国内镜像源。执行以下命令添加清华源conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/ conda config --set show_channel_urls yes清除索引缓存conda clean -i。指定更宽泛的包版本或者从其他渠道如conda-forge寻找包conda install -c conda-forge package_name。9. 进阶技巧与最佳实践掌握了基础操作后下面这些技巧能让你的虚拟环境使用体验更上一层楼。9.1 使用 .venv 作为环境目录名越来越多的工具如Python的venv模块本身、一些IDE开始默认寻找或推荐使用.venv作为虚拟环境目录名。它是一个隐藏文件夹可以让项目根目录更整洁并且被许多.gitignore模板默认忽略避免误提交。python3 -m venv .venv source .venv/bin/activate9.2 将虚拟环境目录排除在版本控制之外虚拟环境目录venv/或.venv/绝对不应该提交到Git等版本控制系统。确保你的.gitignore文件包含如下行# Virtual Environment venv/ .venv/ env/9.3 使用 pipreqs 智能生成 requirements.txtpip freeze会导出环境中的所有包包括你不需要的间接依赖。pipreqs工具可以只扫描项目代码中import的语句生成最小化的依赖列表更干净。# 首先在虚拟环境中安装 pip install pipreqs # 然后在项目根目录运行 pipreqs . --encodingutf8 --force9.4 为不同Python版本创建环境有时你需要测试项目在不同Python版本下的兼容性。可以使用deadsnakesPPA适用于Ubuntu安装多个Python版本然后用指定版本创建虚拟环境# 添加deadsnakes PPA并安装Python 3.11 sudo add-apt-repository ppa:deadsnakes/ppa sudo apt update sudo apt install python3.11 python3.11-venv # 使用Python 3.11创建虚拟环境 python3.11 -m venv venv-3119.5 在Shell配置中简化激活流程如果你经常在几个项目间切换可以在~/.bashrc或~/.zshrc中添加别名或函数来快速激活环境。例如添加一个函数function act() { if [ -d .venv ]; then source .venv/bin/activate elif [ -d venv ]; then source venv/bin/activate else echo 未找到虚拟环境目录 (.venv 或 venv)。 fi }保存后执行source ~/.bashrc以后进入项目目录只需输入act即可尝试激活虚拟环境。虚拟环境是Python开发者的基石工具它代表的是一种清晰、隔离、可复现的项目管理哲学。从今天起养成“每个项目先建环境”的习惯你会发现项目依赖管理带来的烦恼将大大减少。无论是运行一个从GitHub上发现的有趣脚本还是部署一个复杂的企业级应用这套流程都能为你提供一个坚实可靠的起点。