1. 为什么在Ubuntu上装Python和pip远不止“apt install”那么简单如果你刚接触Linux开发或者从Windows/macOS迁移过来第一次在Ubuntu上配置Python环境大概率会直接搜索“Ubuntu安装Python”然后照着教程敲下sudo apt install python3 python3-pip。这没错对于很多简单场景这条命令确实能让你快速跑起来。但作为一个在Linux环境下折腾过无数项目的过来人我得告诉你事情远没有这么简单。这条看似简单的命令背后隐藏着版本管理、系统依赖、虚拟环境、权限隔离等一系列“坑”很多新手在项目做到一半时才发现环境混乱为时已晚。Ubuntu系统本身预装了Python但那个版本通常是系统维护用的比如Ubuntu 22.04 LTS预装Python 3.10你的应用可能需要更新的3.11、3.12或者因为某些依赖被迫使用旧的3.8。直接用apt安装的Python和pip其二进制文件和包安装路径是全局的这意味着你安装的任何第三方包如numpy,requests都会污染系统环境并且不同项目对同一个包的不同版本需求会产生直接冲突。更棘手的是系统工具如apt本身可能依赖特定的Python包你一不小心升级了某个包可能导致系统功能异常。所以我们今天要聊的不是一条命令的“安装”而是一套在Ubuntu上构建健壮、可维护、项目隔离的Python开发环境的“方法论”。我会带你从最基础的apt安装讲起然后深入到为什么以及如何用pyenv进行多版本管理最后用venv或virtualenv为每个项目创建独立的沙箱。整个过程我会把那些官方文档里不会写的“坑”和“技巧”掰开揉碎讲清楚确保你配置一次就能应对绝大多数开发场景。2. 基础安装使用APT包管理器与潜在陷阱我们先从最直接的方法开始了解系统级安装的流程和局限性。Ubuntu的APTAdvanced Package Tool是强大的包管理器它能处理软件及其所有依赖的安装。2.1 更新系统并安装Python 3在安装任何新软件前更新本地软件包索引是一个好习惯这能确保你获取到仓库中最新的版本信息和依赖关系。sudo apt update sudo apt upgrade -y更新完成后安装Python 3。在较新的Ubuntu版本20.04及以上中python命令通常默认链接到Python 2如果已安装或不存在而python3才是Python 3的解释器。sudo apt install python3安装完成后可以通过以下命令验证安装是否成功以及查看具体版本python3 --version # 输出可能类似Python 3.10.12注意在终端里python和python3是两个不同的命令。除非你手动配置了别名或软链接否则请始终使用python3来调用我们刚安装的Python解释器。这是避免与可能残留的Python 2环境混淆的关键。2.2 安装pip3Python的包管理利器Python的强大离不开丰富的第三方库而pip就是安装和管理这些库的标准工具。在Ubuntu中与Python 3对应的包叫python3-pip。sudo apt install python3-pip同样安装成功后验证pip3 --version # 输出可能类似pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)这个输出信息很重要它告诉了你三件事1) pip的版本2) pip自身的安装路径3) 它关联的Python解释器版本。请确保它关联的Python版本与你使用的python3 --version一致。2.3 APT安装方式的局限性分析到这里一个基础的Python环境就搭建好了。你可以用pip3 install package_name来安装任何你想要的包。但是让我们深入看看这种方式的几个核心问题版本锁定且陈旧APT仓库中的软件版本倾向于稳定而非最新。Ubuntu 22.04 LTS的仓库可能只提供Python 3.10而你的项目可能需要3.11的新特性如tomllib模块或3.12的性能改进。通过APT升级到次要版本如从3.10.6到3.10.12是可能的但升级主要版本如从3.10到3.11通常非常困难且容易破坏系统。全局安装与权限问题用sudo pip3 install安装的包会被放在系统级的目录如/usr/local/lib/python3.10/dist-packages/。这带来了两个麻烦第一你需要sudo权限存在安全风险第二所有用户、所有项目都共享这些包。项目A需要Django4.1项目B需要Django3.2冲突无法解决。可能干扰系统工具Ubuntu的某些系统组件如apt、gnome-terminal可能依赖特定版本的Python包。如果你用pip全局升级了某个包例如requests可能会导致这些系统工具报错或行为异常。因此对于个人学习或一次性脚本APT安装足够用。但对于严肃的软件开发这仅仅是第一步。我们需要更精细的控制。3. 进阶管理使用Pyenv实现多版本Python自由切换为了解决版本锁定的问题pyenv是一个完美的工具。它允许你在用户主目录下安装多个独立的Python版本并轻松地在它们之间切换。它通过修改shell的PATH环境变量优先级来实现完全不影响系统自带的Python。3.1 安装Pyenv及其依赖pyenv的安装不通过APT而是通过克隆其Git仓库。首先安装必要的编译依赖因为pyenv需要从源代码编译Python。sudo apt update sudo apt install -y make build-essential libssl-dev zlib1g-dev \ libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \ libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev这些库是编译Python及其核心模块如ssl,sqlite3,zlib所必需的。缺少它们可能会导致编译失败或编译出的Python功能不全。接下来使用官方安装脚本安装pyenv。这里我们使用curl下载并执行脚本。curl https://pyenv.run | bash这个脚本会将pyenv克隆到~/.pyenv目录并自动在你的shell配置文件如~/.bashrc末尾添加必要的初始化代码。3.2 配置Shell环境并安装特定Python版本安装脚本完成后需要重启终端或者重新加载shell配置以使pyenv生效。# 对于bash用户 exec $SHELL # 或者 source ~/.bashrc # 对于zsh用户Ubuntu默认是bash但如果你用了zsh source ~/.zshrc现在你可以查看所有可通过pyenv安装的Python版本了pyenv install --list | grep -v ^[a-z] | grep -v ^-\|^\.\|^[0-9\.-]*[a-z] | head -20这个命令过滤了非稳定版本列出前20个可用的稳定版本。假设我们需要安装Python 3.11.9和3.12.2pyenv install 3.11.9 pyenv install 3.12.2安装过程需要从源代码编译耗时较长几分钟到十几分钟取决于机器性能。pyenv会自动下载源码、解压、编译并安装到~/.pyenv/versions/目录下。3.3 管理版本与设置全局/本地默认安装完成后查看已安装的版本pyenv versions输出会显示系统版本system和你刚安装的版本当前激活的版本前会有一个*号。你可以设置一个全局默认版本这会影响你所有终端会话pyenv global 3.11.9验证一下python --version # 现在应该输出 Python 3.11.9 which python # 路径应该是 ~/.pyenv/shims/pythonpyenv更强大的功能在于“本地”per-project版本设置。进入你的项目目录然后cd ~/my_project pyenv local 3.12.2这会在当前目录下创建一个.python-version文件里面写着3.12.2。以后只要你进入这个目录或其子目录pyenv会自动将Python版本切换为3.12.2。这对于管理多个不同Python版本要求的项目极其方便。实操心得我习惯为每个项目目录都设置一个pyenv local版本。这样即使我在多个项目终端间切换也无需手动干预环境自动就位。另外编译安装Python时如果失败请仔细检查终端输出最常见的错误就是第一步的编译依赖没装全。4. 环境隔离为每个项目创建独立的虚拟环境解决了Python解释器版本的问题我们再来解决项目依赖隔离的问题。这就是虚拟环境Virtual Environment的用武之地。虚拟环境是一个包含特定Python解释器副本、pip以及独立site-packages目录的隔离目录。每个项目独占一个虚拟环境其中的包安装、升级、删除都不会影响其他项目或系统环境。Python 3.3及以上版本内置了venv模块它是创建虚拟环境的首选工具。4.1 使用venv创建并激活虚拟环境假设我们的项目目录是~/projects/my_awesome_app并且我们已经通过pyenv local将目录的Python版本设置为3.11.9。cd ~/projects/my_awesome_app # 创建虚拟环境环境目录通常命名为 venv 或 .venv python -m venv venv这条命令会在当前目录下创建一个名为venv的文件夹里面包含了Python解释器、pip、setuptools等的独立副本。创建完成后需要“激活”这个环境这样你的shell才会知道使用这个环境里的Python和pip。# 激活虚拟环境 source venv/bin/activate激活后你的命令行提示符PS1通常会发生变化前面会加上(venv)字样这是一个非常直观的提示告诉你当前正处于哪个虚拟环境中。(venv) userhost:~/projects/my_awesome_app$现在你执行的python和pip命令指向的都是venv/bin/下的那个副本与全局环境完全无关。可以验证一下which python # 输出: /home/user/projects/my_awesome_app/venv/bin/python which pip # 输出: /home/user/projects/my_awesome_app/venv/bin/pip4.2 在虚拟环境中管理依赖在激活的虚拟环境中你可以安全地使用pip install安装项目所需的任何包无需sudo。(venv) pip install django4.2 requests beautifulsoup4所有包都会被安装到venv/lib/python3.11/site-packages/目录下。你可以使用pip freeze命令生成当前环境所有包及其精确版本的列表这个列表通常被保存到requirements.txt文件中用于在其他机器上复现相同的环境。(venv) pip freeze requirements.txtrequirements.txt文件内容类似asgiref3.7.2 beautifulsoup44.12.2 Django4.2 requests2.31.0 ...当你在新的地方或新的虚拟环境需要安装这些依赖时只需pip install -r requirements.txt工作完成后可以退出当前虚拟环境deactivate提示符会恢复原样Python和pip也回到了全局或pyenv设置的状态。4.3 虚拟环境的最佳实践与避坑指南环境目录不入库务必在你的版本控制系统如Git的.gitignore文件中添加venv/、.venv/、env/等虚拟环境目录名。只将requirements.txt纳入版本管理。何时创建环境我的习惯是在git init初始化项目仓库后紧接着就创建虚拟环境。确保开发环境从一开始就是隔离的。VSCode集成如果你使用VSCode在打开项目文件夹后按CtrlShiftP输入“Python: Select Interpreter”然后选择虚拟环境中的python可执行文件路径如./venv/bin/python。这样VSCode的终端、调试器、语言服务器都会自动使用该环境。PyCharm等IDE这些IDE在创建新项目时通常提供“New environment using Virtualenv”的选项自动帮你创建并关联虚拟环境非常方便。--system-site-packages参数慎用python -m venv venv --system-site-packages会创建允许访问全局site-packages的虚拟环境。这通常不是好主意因为它破坏了隔离性可能导致难以排查的依赖冲突。除非你有非常特殊且明确的理由否则不要使用这个参数。5. 优化与配置提升pip体验与解决网络问题在虚拟环境中pip是我们最常打交道的工具。优化它的使用体验能极大提升效率。5.1 升级pip与setuptools新创建的虚拟环境里的pip和setuptools版本可能不是最新的。首先升级它们(venv) python -m pip install --upgrade pip setuptools wheel使用python -m pip而不是直接的pip命令是一个好习惯它能确保调用的是当前Python解释器对应的pip模块避免因PATH配置问题调用到错误的pip。5.2 配置pip使用国内镜像源直接从Python官方的PyPI仓库下载包在国内速度可能很慢甚至超时。将源切换到国内镜像能极大加速下载。国内常用的镜像源有清华大学https://pypi.tuna.tsinghua.edu.cn/simple阿里云https://mirrors.aliyun.com/pypi/simple/中国科技大学https://pypi.mirrors.ustc.edu.cn/simple/有几种配置方式方式一临时使用单次安装pip install -i https://pypi.tuna.tsinghua.edu.cn/simple some-package方式二设为默认推荐在用户主目录下创建或修改pip配置文件。mkdir -p ~/.pip # 如果目录不存在则创建 # 对于Linux/macOS cat ~/.pip/pip.conf EOF [global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn EOF或者在虚拟环境中激活状态下这个配置只对该环境生效优先级更高(venv) pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple (venv) pip config set install.trusted-host pypi.tuna.tsinghua.edu.cn配置完成后后续所有的pip install命令都会默认使用清华源。5.3 理解pip安装路径与缓存了解pip把包装在哪里对于排查问题很有帮助。在虚拟环境中(venv) python -m site这个命令会列出所有的site-packages目录路径你安装的第三方包就在其中。pip会缓存下载的包文件.whl或.tar.gz避免重复下载。缓存位置通常在~/.cache/pip/。如果你遇到安装问题可以尝试清除缓存pip cache purge6. 实战工作流从零搭建一个Django项目的完整环境让我们把上面的所有步骤串联起来完成一个真实场景的演练在Ubuntu 22.04上为一个新的Django项目配置专用环境要求使用Python 3.11。步骤1系统准备与Pyenv安装# 1. 更新系统 sudo apt update sudo apt upgrade -y # 2. 安装Pyenv编译依赖 sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev # 3. 安装Pyenv curl https://pyenv.run | bash # 4. 将pyenv初始化添加到shell配置假设是bash echo export PATH$HOME/.pyenv/bin:$PATH ~/.bashrc echo eval $(pyenv init --path) ~/.bashrc echo eval $(pyenv virtualenv-init -) ~/.bashrc # 如果你以后想用pyenv-virtualenv插件 source ~/.bashrc步骤2安装指定Python版本并设置全局默认# 5. 安装Python 3.11.9 pyenv install 3.11.9 # 6. 设为全局默认可选也可以只设本地 pyenv global 3.11.9 exec $SHELL python --version # 确认是3.11.9步骤3创建项目并初始化虚拟环境# 7. 创建项目目录 mkdir ~/projects/my_django_site cd ~/projects/my_django_site # 8. 为此目录设置本地Python版本强化约束 pyenv local 3.11.9 # 9. 创建虚拟环境 python -m venv .venv # 我更喜欢用 .venv 作为隐藏目录 # 10. 激活虚拟环境 source .venv/bin/activate步骤4在虚拟环境中配置pip并安装Django# 11. 升级pip和setuptools python -m pip install --upgrade pip setuptools wheel # 12. 配置pip清华镜像源永久生效于此环境 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip config set install.trusted-host pypi.tuna.tsinghua.edu.cn # 13. 安装Django及其他项目依赖 pip install django4.2 psycopg2-binary # 假设使用PostgreSQL # 14. 生成依赖清单 pip freeze requirements.txt步骤5开始Django项目开发# 15. 创建Django项目 django-admin startproject config . # 16. 运行开发服务器测试 python manage.py migrate python manage.py runserver现在打开浏览器访问http://127.0.0.1:8000你应该能看到Django的欢迎页面。整个环境是独立、可复现的。项目根目录下的.python-version文件记录了Python版本.venv目录是隔离的环境requirements.txt记录了所有依赖。你可以将整个项目目录排除.venv打包或推送到Git其他协作者在克隆代码后只需要执行pyenv install如果需要、python -m venv .venv、pip install -r requirements.txt即可获得一模一样的环境。这套组合拳——pyenv管理解释器版本 venv隔离项目依赖——是我经过多年实践验证的、在Ubuntu以及其他Linux发行版和macOS上管理Python开发环境的黄金标准。它清晰、健壮、可维护能让你彻底告别“在我的机器上能跑”的环境问题。刚开始设置可能觉得步骤稍多但一旦成为习惯它会为你节省无数排查环境冲突的时间。
1. 为什么在Ubuntu上装Python和pip远不止“apt install”那么简单如果你刚接触Linux开发或者从Windows/macOS迁移过来第一次在Ubuntu上配置Python环境大概率会直接搜索“Ubuntu安装Python”然后照着教程敲下sudo apt install python3 python3-pip。这没错对于很多简单场景这条命令确实能让你快速跑起来。但作为一个在Linux环境下折腾过无数项目的过来人我得告诉你事情远没有这么简单。这条看似简单的命令背后隐藏着版本管理、系统依赖、虚拟环境、权限隔离等一系列“坑”很多新手在项目做到一半时才发现环境混乱为时已晚。Ubuntu系统本身预装了Python但那个版本通常是系统维护用的比如Ubuntu 22.04 LTS预装Python 3.10你的应用可能需要更新的3.11、3.12或者因为某些依赖被迫使用旧的3.8。直接用apt安装的Python和pip其二进制文件和包安装路径是全局的这意味着你安装的任何第三方包如numpy,requests都会污染系统环境并且不同项目对同一个包的不同版本需求会产生直接冲突。更棘手的是系统工具如apt本身可能依赖特定的Python包你一不小心升级了某个包可能导致系统功能异常。所以我们今天要聊的不是一条命令的“安装”而是一套在Ubuntu上构建健壮、可维护、项目隔离的Python开发环境的“方法论”。我会带你从最基础的apt安装讲起然后深入到为什么以及如何用pyenv进行多版本管理最后用venv或virtualenv为每个项目创建独立的沙箱。整个过程我会把那些官方文档里不会写的“坑”和“技巧”掰开揉碎讲清楚确保你配置一次就能应对绝大多数开发场景。2. 基础安装使用APT包管理器与潜在陷阱我们先从最直接的方法开始了解系统级安装的流程和局限性。Ubuntu的APTAdvanced Package Tool是强大的包管理器它能处理软件及其所有依赖的安装。2.1 更新系统并安装Python 3在安装任何新软件前更新本地软件包索引是一个好习惯这能确保你获取到仓库中最新的版本信息和依赖关系。sudo apt update sudo apt upgrade -y更新完成后安装Python 3。在较新的Ubuntu版本20.04及以上中python命令通常默认链接到Python 2如果已安装或不存在而python3才是Python 3的解释器。sudo apt install python3安装完成后可以通过以下命令验证安装是否成功以及查看具体版本python3 --version # 输出可能类似Python 3.10.12注意在终端里python和python3是两个不同的命令。除非你手动配置了别名或软链接否则请始终使用python3来调用我们刚安装的Python解释器。这是避免与可能残留的Python 2环境混淆的关键。2.2 安装pip3Python的包管理利器Python的强大离不开丰富的第三方库而pip就是安装和管理这些库的标准工具。在Ubuntu中与Python 3对应的包叫python3-pip。sudo apt install python3-pip同样安装成功后验证pip3 --version # 输出可能类似pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)这个输出信息很重要它告诉了你三件事1) pip的版本2) pip自身的安装路径3) 它关联的Python解释器版本。请确保它关联的Python版本与你使用的python3 --version一致。2.3 APT安装方式的局限性分析到这里一个基础的Python环境就搭建好了。你可以用pip3 install package_name来安装任何你想要的包。但是让我们深入看看这种方式的几个核心问题版本锁定且陈旧APT仓库中的软件版本倾向于稳定而非最新。Ubuntu 22.04 LTS的仓库可能只提供Python 3.10而你的项目可能需要3.11的新特性如tomllib模块或3.12的性能改进。通过APT升级到次要版本如从3.10.6到3.10.12是可能的但升级主要版本如从3.10到3.11通常非常困难且容易破坏系统。全局安装与权限问题用sudo pip3 install安装的包会被放在系统级的目录如/usr/local/lib/python3.10/dist-packages/。这带来了两个麻烦第一你需要sudo权限存在安全风险第二所有用户、所有项目都共享这些包。项目A需要Django4.1项目B需要Django3.2冲突无法解决。可能干扰系统工具Ubuntu的某些系统组件如apt、gnome-terminal可能依赖特定版本的Python包。如果你用pip全局升级了某个包例如requests可能会导致这些系统工具报错或行为异常。因此对于个人学习或一次性脚本APT安装足够用。但对于严肃的软件开发这仅仅是第一步。我们需要更精细的控制。3. 进阶管理使用Pyenv实现多版本Python自由切换为了解决版本锁定的问题pyenv是一个完美的工具。它允许你在用户主目录下安装多个独立的Python版本并轻松地在它们之间切换。它通过修改shell的PATH环境变量优先级来实现完全不影响系统自带的Python。3.1 安装Pyenv及其依赖pyenv的安装不通过APT而是通过克隆其Git仓库。首先安装必要的编译依赖因为pyenv需要从源代码编译Python。sudo apt update sudo apt install -y make build-essential libssl-dev zlib1g-dev \ libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \ libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev这些库是编译Python及其核心模块如ssl,sqlite3,zlib所必需的。缺少它们可能会导致编译失败或编译出的Python功能不全。接下来使用官方安装脚本安装pyenv。这里我们使用curl下载并执行脚本。curl https://pyenv.run | bash这个脚本会将pyenv克隆到~/.pyenv目录并自动在你的shell配置文件如~/.bashrc末尾添加必要的初始化代码。3.2 配置Shell环境并安装特定Python版本安装脚本完成后需要重启终端或者重新加载shell配置以使pyenv生效。# 对于bash用户 exec $SHELL # 或者 source ~/.bashrc # 对于zsh用户Ubuntu默认是bash但如果你用了zsh source ~/.zshrc现在你可以查看所有可通过pyenv安装的Python版本了pyenv install --list | grep -v ^[a-z] | grep -v ^-\|^\.\|^[0-9\.-]*[a-z] | head -20这个命令过滤了非稳定版本列出前20个可用的稳定版本。假设我们需要安装Python 3.11.9和3.12.2pyenv install 3.11.9 pyenv install 3.12.2安装过程需要从源代码编译耗时较长几分钟到十几分钟取决于机器性能。pyenv会自动下载源码、解压、编译并安装到~/.pyenv/versions/目录下。3.3 管理版本与设置全局/本地默认安装完成后查看已安装的版本pyenv versions输出会显示系统版本system和你刚安装的版本当前激活的版本前会有一个*号。你可以设置一个全局默认版本这会影响你所有终端会话pyenv global 3.11.9验证一下python --version # 现在应该输出 Python 3.11.9 which python # 路径应该是 ~/.pyenv/shims/pythonpyenv更强大的功能在于“本地”per-project版本设置。进入你的项目目录然后cd ~/my_project pyenv local 3.12.2这会在当前目录下创建一个.python-version文件里面写着3.12.2。以后只要你进入这个目录或其子目录pyenv会自动将Python版本切换为3.12.2。这对于管理多个不同Python版本要求的项目极其方便。实操心得我习惯为每个项目目录都设置一个pyenv local版本。这样即使我在多个项目终端间切换也无需手动干预环境自动就位。另外编译安装Python时如果失败请仔细检查终端输出最常见的错误就是第一步的编译依赖没装全。4. 环境隔离为每个项目创建独立的虚拟环境解决了Python解释器版本的问题我们再来解决项目依赖隔离的问题。这就是虚拟环境Virtual Environment的用武之地。虚拟环境是一个包含特定Python解释器副本、pip以及独立site-packages目录的隔离目录。每个项目独占一个虚拟环境其中的包安装、升级、删除都不会影响其他项目或系统环境。Python 3.3及以上版本内置了venv模块它是创建虚拟环境的首选工具。4.1 使用venv创建并激活虚拟环境假设我们的项目目录是~/projects/my_awesome_app并且我们已经通过pyenv local将目录的Python版本设置为3.11.9。cd ~/projects/my_awesome_app # 创建虚拟环境环境目录通常命名为 venv 或 .venv python -m venv venv这条命令会在当前目录下创建一个名为venv的文件夹里面包含了Python解释器、pip、setuptools等的独立副本。创建完成后需要“激活”这个环境这样你的shell才会知道使用这个环境里的Python和pip。# 激活虚拟环境 source venv/bin/activate激活后你的命令行提示符PS1通常会发生变化前面会加上(venv)字样这是一个非常直观的提示告诉你当前正处于哪个虚拟环境中。(venv) userhost:~/projects/my_awesome_app$现在你执行的python和pip命令指向的都是venv/bin/下的那个副本与全局环境完全无关。可以验证一下which python # 输出: /home/user/projects/my_awesome_app/venv/bin/python which pip # 输出: /home/user/projects/my_awesome_app/venv/bin/pip4.2 在虚拟环境中管理依赖在激活的虚拟环境中你可以安全地使用pip install安装项目所需的任何包无需sudo。(venv) pip install django4.2 requests beautifulsoup4所有包都会被安装到venv/lib/python3.11/site-packages/目录下。你可以使用pip freeze命令生成当前环境所有包及其精确版本的列表这个列表通常被保存到requirements.txt文件中用于在其他机器上复现相同的环境。(venv) pip freeze requirements.txtrequirements.txt文件内容类似asgiref3.7.2 beautifulsoup44.12.2 Django4.2 requests2.31.0 ...当你在新的地方或新的虚拟环境需要安装这些依赖时只需pip install -r requirements.txt工作完成后可以退出当前虚拟环境deactivate提示符会恢复原样Python和pip也回到了全局或pyenv设置的状态。4.3 虚拟环境的最佳实践与避坑指南环境目录不入库务必在你的版本控制系统如Git的.gitignore文件中添加venv/、.venv/、env/等虚拟环境目录名。只将requirements.txt纳入版本管理。何时创建环境我的习惯是在git init初始化项目仓库后紧接着就创建虚拟环境。确保开发环境从一开始就是隔离的。VSCode集成如果你使用VSCode在打开项目文件夹后按CtrlShiftP输入“Python: Select Interpreter”然后选择虚拟环境中的python可执行文件路径如./venv/bin/python。这样VSCode的终端、调试器、语言服务器都会自动使用该环境。PyCharm等IDE这些IDE在创建新项目时通常提供“New environment using Virtualenv”的选项自动帮你创建并关联虚拟环境非常方便。--system-site-packages参数慎用python -m venv venv --system-site-packages会创建允许访问全局site-packages的虚拟环境。这通常不是好主意因为它破坏了隔离性可能导致难以排查的依赖冲突。除非你有非常特殊且明确的理由否则不要使用这个参数。5. 优化与配置提升pip体验与解决网络问题在虚拟环境中pip是我们最常打交道的工具。优化它的使用体验能极大提升效率。5.1 升级pip与setuptools新创建的虚拟环境里的pip和setuptools版本可能不是最新的。首先升级它们(venv) python -m pip install --upgrade pip setuptools wheel使用python -m pip而不是直接的pip命令是一个好习惯它能确保调用的是当前Python解释器对应的pip模块避免因PATH配置问题调用到错误的pip。5.2 配置pip使用国内镜像源直接从Python官方的PyPI仓库下载包在国内速度可能很慢甚至超时。将源切换到国内镜像能极大加速下载。国内常用的镜像源有清华大学https://pypi.tuna.tsinghua.edu.cn/simple阿里云https://mirrors.aliyun.com/pypi/simple/中国科技大学https://pypi.mirrors.ustc.edu.cn/simple/有几种配置方式方式一临时使用单次安装pip install -i https://pypi.tuna.tsinghua.edu.cn/simple some-package方式二设为默认推荐在用户主目录下创建或修改pip配置文件。mkdir -p ~/.pip # 如果目录不存在则创建 # 对于Linux/macOS cat ~/.pip/pip.conf EOF [global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn EOF或者在虚拟环境中激活状态下这个配置只对该环境生效优先级更高(venv) pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple (venv) pip config set install.trusted-host pypi.tuna.tsinghua.edu.cn配置完成后后续所有的pip install命令都会默认使用清华源。5.3 理解pip安装路径与缓存了解pip把包装在哪里对于排查问题很有帮助。在虚拟环境中(venv) python -m site这个命令会列出所有的site-packages目录路径你安装的第三方包就在其中。pip会缓存下载的包文件.whl或.tar.gz避免重复下载。缓存位置通常在~/.cache/pip/。如果你遇到安装问题可以尝试清除缓存pip cache purge6. 实战工作流从零搭建一个Django项目的完整环境让我们把上面的所有步骤串联起来完成一个真实场景的演练在Ubuntu 22.04上为一个新的Django项目配置专用环境要求使用Python 3.11。步骤1系统准备与Pyenv安装# 1. 更新系统 sudo apt update sudo apt upgrade -y # 2. 安装Pyenv编译依赖 sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev # 3. 安装Pyenv curl https://pyenv.run | bash # 4. 将pyenv初始化添加到shell配置假设是bash echo export PATH$HOME/.pyenv/bin:$PATH ~/.bashrc echo eval $(pyenv init --path) ~/.bashrc echo eval $(pyenv virtualenv-init -) ~/.bashrc # 如果你以后想用pyenv-virtualenv插件 source ~/.bashrc步骤2安装指定Python版本并设置全局默认# 5. 安装Python 3.11.9 pyenv install 3.11.9 # 6. 设为全局默认可选也可以只设本地 pyenv global 3.11.9 exec $SHELL python --version # 确认是3.11.9步骤3创建项目并初始化虚拟环境# 7. 创建项目目录 mkdir ~/projects/my_django_site cd ~/projects/my_django_site # 8. 为此目录设置本地Python版本强化约束 pyenv local 3.11.9 # 9. 创建虚拟环境 python -m venv .venv # 我更喜欢用 .venv 作为隐藏目录 # 10. 激活虚拟环境 source .venv/bin/activate步骤4在虚拟环境中配置pip并安装Django# 11. 升级pip和setuptools python -m pip install --upgrade pip setuptools wheel # 12. 配置pip清华镜像源永久生效于此环境 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip config set install.trusted-host pypi.tuna.tsinghua.edu.cn # 13. 安装Django及其他项目依赖 pip install django4.2 psycopg2-binary # 假设使用PostgreSQL # 14. 生成依赖清单 pip freeze requirements.txt步骤5开始Django项目开发# 15. 创建Django项目 django-admin startproject config . # 16. 运行开发服务器测试 python manage.py migrate python manage.py runserver现在打开浏览器访问http://127.0.0.1:8000你应该能看到Django的欢迎页面。整个环境是独立、可复现的。项目根目录下的.python-version文件记录了Python版本.venv目录是隔离的环境requirements.txt记录了所有依赖。你可以将整个项目目录排除.venv打包或推送到Git其他协作者在克隆代码后只需要执行pyenv install如果需要、python -m venv .venv、pip install -r requirements.txt即可获得一模一样的环境。这套组合拳——pyenv管理解释器版本 venv隔离项目依赖——是我经过多年实践验证的、在Ubuntu以及其他Linux发行版和macOS上管理Python开发环境的黄金标准。它清晰、健壮、可维护能让你彻底告别“在我的机器上能跑”的环境问题。刚开始设置可能觉得步骤稍多但一旦成为习惯它会为你节省无数排查环境冲突的时间。
