各位同行说起Python多版本共存这件事我估计不少人都经历过那种“血压飙升”的瞬间。特别是前几年还在维护Python 2遗留项目的人一边是线上跑得好好的Django老系统只能依赖2.7环境一边是新项目需要Python 3.8以上的特性结果同一台机器上两个版本互相打架。最典型的就是你在终端敲pip install明明感觉装上了一import却提示找不到模块折腾半天发现 pip 指向的是另一个版本的Python。今天这篇文章我就把Python 2和Python 3在同一系统下多版本共存的完整方案讲明白从原理到底层机制从工具选型到实战步骤再到各种归档级的踩坑记录全部摊开来讲。这篇内容适合谁看只要你需要维护老项目、又要写新代码或者需要在同一台开发机、同一台服务器上跑多个Python版本那这篇文章就是给你准备的。我会重点讲Linux下的方案因为生产环境里Linux最为常见同时也会顺带提一下macOS和Windows的处理思路。读完你不仅能装好环境更重要的是能理解这里面每一步到底在做什么以后遇到问题排查起来才有方向感。1. 整体设计思路先搞清楚“共存”到底在解决什么问题1.1 核心痛点Python版本隔离为什么这么难Python 2和Python 3不兼容这是历史遗留的现实。但很多人在处理共存问题时思路一开始就错了跑去改系统默认的python软链接或者直接把某个版本卸载重装结果越弄越乱。要理清这个问题得先明白Python安装到系统里之后到底有哪几层东西在起作用。第一层是解释器本体也就是python2和python3这两个可执行文件它们各自指向不同版本的二进制。第二层是标准库和第三方包Python 2和Python 3的site-packages目录是分开的如果两个版本共用同一个第三方库目录那绝对会出乱子。第三层是命令行工具的入口脚本比如pip、pytest、supervisor这些工具它们安装时会在bin目录下生成可执行文件文件头部用shebang指定了用哪个解释器运行。这三层只要有一层指向混乱就会出现“装了包找不到、命令执行报错、版本对不上号”的问题。所以共存的本质不是简单地“装两个Python”而是要建立一套清晰的隔离和切换机制让操作系统、终端、项目都能准确找到自己需要的那一套环境。1.2 方案选型为什么推荐“pyenv venv”组合市面上处理多版本共存的工具有不少我拿它们做过对比各有优劣。第一种是直接用系统的包管理器比如apt安装python2.7和python3.8然后通过update-alternatives切换。这个方案的优点是安装简单缺点是版本号被系统锁死想装一个“非官方”的Python小版本就麻烦了而且系统级包管理器升级时可能覆盖配置风险不小。另外update-alternatives只是切换命令行入口第三方库和工具脚本依然可能混乱。第二种是Anaconda/Miniconda。conda确实是多版本管理的利器尤其是数据科学领域环境隔离做得非常干净Windows、macOS、Linux通吃。但它也有自己的问题conda创建的环境默认带了一套完整的科学计算包体积大、依赖重和系统Python的交互逻辑也比较自成一体。对于只想单纯管理Python版本、不想被conda生态绑定的场景来说有点杀鸡用牛刀。第三种是我最常用的方案pyenv 管理多个Python解释器版本venv 管理每个项目独立的第三方包环境。这两个工具各管一层互不干扰。pyenv只负责搞定解释器本身让不同的Python版本可以同时存在、快速切换venv则基于某个特定的Python解释器创建出独立的虚拟环境每个环境有自己独立的site-packages目录互相隔离。这样组合起来从上到下每一层都清清楚楚。为什么最终选择pyenv因为它在Linux/macOS上表现最稳定工作原理也很透明通过修改PATH环境变量和一段shell脚本钩子机制把python这个命令“劫持”到指定版本的可执行文件上。我们不需要动系统自带的Python安全性很高。1.3 版本兼容性矩阵Python 2和Python 3的生态差异既然要共存就不得不面对两者的生态差异。Python 2.7是Python 2系列的最后一个版本官方在2020年1月1日停止维护虽然不再更新但大量历史项目仍在运行。Python 3则持续推进3.6到3.12每个版本都有新特性但不少第三方库对版本也有要求。规划共存方案时我一般会建一张兼容性清单列出项目中使用的第三方库与Python版本的对应关系。比如MySQLdb只支持Python 2换到Python 3就得用PyMySQL或者mysqlclientTwisted在Python 3.6以上才有稳定支持而新版Django早就抛弃了Python 2。只有把依赖库的版本要求摸清楚才能确定需要装哪几个Python解释器版本。2. 核心细节解析pyenv的安装、编译与切换机制2.1 环境准备依赖库一个都不能少先声明一下下面的操作基于Ubuntu 20.04 LTS其他Linux发行版的包名略有差异但思路一样。pyenv安装Python时其实是从源码编译的不是下载现成的二进制包所以系统里必须装齐编译工具链和依赖库。我最初偷懒少装了一个libssl-dev结果Python编译出来之后pip用不了HTTPS装啥都报SSL错误折腾到怀疑人生。执行以下命令安装编译依赖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这里每个依赖都有它存在的理由zlib1g-dev是Python的zlib压缩模块需要的缺了它ensurepip可能直接失败libreadline-dev影响交互式环境的上下键历史功能libsqlite3-dev则关系到sqlite3标准库能否正常导入。如果你打算用Python 3.7以上的版本libffi-dev尤其重要否则ctypes模块会出问题。macOS用户需要先装Xcode Command Line Tools然后执行brew install openssl readline sqlite3 xz zlib tcl-tk。Windows用户呢我的建议是直接用Python官网的安装包装多个版本然后通过py启动器来切换pyenv在Windows原生环境下的体验确实一般。2.2 pyenv安装与配置把PATH机制握在手里依赖安装好之后用git把pyenv克隆到用户目录下git clone https://github.com/pyenv/pyenv.git ~/.pyenv然后在~/.bashrc最末尾追加这几行配置export PYENV_ROOT$HOME/.pyenv export PATH$PYENV_ROOT/bin:$PATH eval $(pyenv init -)执行source ~/.bashrc让配置生效然后输入pyenv --version确认安装成功。这里要重点说一下eval $(pyenv init -)的作用它会在shell里注册一个名为pyenv的shell函数这个函数能拦截你敲的python、pip命令根据pyenv当前的配置动态决定把它们解析到哪个真实的解释器。这就是pyenv切换版本的核心机制不是简单替换软链接而是在命令执行前动态重定向。如果你用的是zsh把.bashrc换成.zshrc即可。修改完配置之后建议新开一个终端窗口避免当前shell环境没加载最新PATH配置。2.3 安装Python 2.7与Python 3.x版本选择与编译参数接下来就是真正安装Python解释器了。先列出pyenv里可用的所有版本号pyenv install --list这个列表非常长包含了CPython、Anaconda、PyPy等各种发行版。我们只需要CPython并且注意区分版本号。以我的项目环境为例老项目需要Python 2.7.18新项目需要Python 3.8.18和Python 3.11.9分别执行安装命令pyenv install 2.7.18 pyenv install 3.8.18 pyenv install 3.11.9第一次编译通常需要几分钟取决于机器性能。安装过程中会输出编译日志如果出现错误在日志末尾能看到具体缺少哪个依赖。有一种情况值得注意如果机器内存比较小Python 3.8以上的版本编译时可能会因为并行编译导致内存不足可以在编译前设置MAKEFLAGS-j1来单线程编译代价是更长的编译时间。另外如果公司内网环境无法访问GitHub和Python官方源码站pyenv install会直接失败。解决方案是手动下载源码包放到~/.pyenv/cache目录下pyenv发现缓存里有对应版本的源码包编译时就会直接用本地的不再联网下载。这个离线安装的细节在生产环境里极其好用。2.4 版本切换的三种姿势global、local、shellpyenv装好多个版本后切换方式有三种对应不同粒度的使用场景。全局切换pyenv global 3.11.9意思是整个用户环境下默认使用Python 3.11.9。这个设置会写入~/.pyenv/version文件打开任何终端都生效。目录级切换pyenv local 2.7.18这条命令会在当前目录生成一个.python-version文件内容就是2.7.18。pyenv会自动识别当前目录下有没有这个文件有的话就切换成对应版本。这个特性非常实用进入老项目目录自动切到Python 2.7进入新项目目录自动切到Python 3.11团队协作时把这个文件提交到仓库大家环境就统一了。会话级切换pyenv shell 3.8.18只在当前终端会话内临时切换关闭终端就失效适合临时跑某个脚本的场景。用pyenv versions命令可以看到当前用户下所有已安装的版本以及当前生效的版本带星号的那个就是当前正在使用的。我个人习惯用pyenv version查看当前版本命令更短输出也更直接。2.5 实测验证检查解释器路径与pip指向安装并切换之后一定要做一次完整的自检。我每次配完新环境都会跑一遍下面的命令which python python --version which pip pip --version python -c import sys; print(sys.executable)which python拿到的是pyenv shim的路径也就是~/.pyenv/shims/python这是pyenv生成的一个脚本转发层不是真正的解释器。执行时它会根据.python-version文件的设置把调用转发给真正的解释器。python --version则能看到当前实际生效的Python版本。关键看pip --version的输出它会明确告诉你当前pip归属于哪个Python解释器、装在哪个目录下面。正常情况下输出类似pip 22.0.4 from /home/user/.pyenv/versions/3.11.9/lib/python3.11/site-packages/pip (python 3.11)如果你发现pip指向的版本和python指向的不一致那就要检查是不是同时装了系统自带的pip导致PATH环境变量里系统路径排在pyenv路径前面。这种情况虽然不常见但一旦出现用echo $PATH看一下顺序就能定位。3. 实操过程从零搭建一套完整的双版本环境3.1 创建项目虚拟环境不同项目不同沙盒解释器层面的共存解决之后还剩一个同样关键的问题第三方包怎么隔离。举个真实例子项目A用Python 2.7跑Django 1.11依赖的django-redis版本是4.x项目B用Python 3.11跑Django 4.2依赖的django-redis是5.x。如果两个项目共用一套site-packages那基本就是灾难装一个包把另一个项目的依赖覆盖了。所以每个项目必须建独立虚拟环境。pyenv提供了一个很好用的插件叫pyenv-virtualenv可以在pyenv的版本体系里创建和管理虚拟环境。先安装插件git clone https://github.com/pyenv/pyenv-virtualenv.git ~/.pyenv/plugins/pyenv-virtualenv然后执行pyenv virtualenv 2.7.18 my-legacy-project pyenv virtualenv 3.11.9 my-new-project创建好之后pyenv versions里就会多出两个带my-legacy-project和my-new-project后缀的环境名。在对应项目目录里执行pyenv local my-legacy-project这样进入目录后自动激活对应的虚拟环境python和pip都指向虚拟环境内的解释器和包目录。如果你不想装插件Python 3.3以上版本自带的venv模块也能干这事python3.11 -m venv /path/to/venv source /path/to/venv/bin/activate区别在于venv创建的虚拟环境和pyenv之间没有联动关系激活方式靠source命令直接修改PATH环境变量项目管理上稍微麻烦一点但胜在干净无插件依赖。两种方式看个人喜好。3.2 pip源配置与依赖安装30秒搞定包管理虚拟环境激活之后安装依赖跟平时一样用pip即可。国内网络环境访问默认的PyPI源速度很慢我一般会先配置一个国内镜像源。方法是在用户目录下编辑~/.pip/pip.confLinux或%APPDATA%\pip\pip.iniWindows[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cnPython 2.7和Python 3的pip都读同一份配置文件所以只改一次就够了。注意trusted-host是必须的否则pip会拒绝连接非HTTPS源。安装依赖时有个小经验如果项目里有requirements.txt先不要一上来就pip install -r requirements.txt先装pip自身和环境核心依赖把pip升级到最新版尤其是Python 2.7环境老版本的pip连manylinux2014格式的wheel包都识别不了安装会报Invalid wheel filename错误。3.3 一个完整案例同一服务器部署两个Python项目光讲理论不落地是耍流氓我拿一个实际场景来演示同一台服务器上同时部署一个Python 2.7的旧后台和一个Python 3.11的新服务。服务器上先确保pyenv装好然后执行两次pyenv install把两个解释器都装好。接着为两个项目分别创建虚拟环境并安装依赖mkdir -p /srv/projects/legacy cd /srv/projects/legacy pyenv local legacy-env pip install -r requirements.txt mkdir -p /srv/projects/newapi cd /srv/projects/newapi pyenv local newapi-env pip install -r requirements.txt两个项目的目录下都会生成.python-version文件分别写着legacy-env和newapi-env。使用systemd管理服务时ExecStart里直接写全路径ExecStart/root/.pyenv/shims/python /srv/projects/legacy/manage.py runserver 0.0.0.0:8001 ExecStart/root/.pyenv/shims/python /srv/projects/newapi/app.py 0.0.0.0:8002这里直接用shims路径好处是systemd不需要读取shell配置也能通过pyenv shim转发到正确的解释器。或者更稳妥的做法是使用虚拟环境内的python绝对路径比如/root/.pyenv/versions/legacy-env/bin/python。我实际部署时会用后一种方式因为shim依赖登录shell环境变量systemd环境下容易出幺蛾子。这套方案上线后运行了两年多两个项目互不干扰升级依赖也互不影响非常稳。3.4 IDE配置VSCode和PyCharm里的多版本切换命令行搞定了IDE也得跟上。VSCode里多版本切换的核心是选择正确的解释器路径。安装了Python插件后按CtrlShiftP打开命令面板输入Python: Select InterpreterVSCode会自动扫描pyenv的虚拟环境列表直接选中对应环境即可。如果需要项目级固定配置在项目根目录创建.vscode/settings.json{ python.defaultInterpreterPath: /root/.pyenv/versions/legacy-env/bin/python }PyCharm的操作类似进入Settings - Project - Python Interpreter点击齿轮选择Add然后选择Existing Environment并填入pyenv虚拟环境的解释器路径最后确认。IDE的自动检测虽然方便但有时候会扫描出很多无关的解释器选择时留意路径是否在~/.pyenv/versions/下面即可。4. 常见问题与排查技巧多版本共存的典型故障记录4.1 编译安装阶段的高频报错报错ERROR: The Python ssl extension was not compiled. Missing the OpenSSL lib?这个报错几乎90%的pyenv编译失败都源于它。原因就是系统缺少OpenSSL开发头文件按前面提到的libssl-dev安装一下然后重新装Python版本。有个细节要提醒Ubuntu 22.04以上系统里OpenSSL可能升级到3.0老版本Python编译时会出现兼容问题需要额外安装libssl1.1或者指定编译参数让Python链接到旧版本库。报错ModuleNotFoundError: No module named _bz2同样典型的依赖缺失症状说明编译时没找到libbz2-dev开发库。安装后重新编译即可。这类问题因为依赖项太多一次装齐的性价比远比逐个报错逐个装要高。报错zipimport.ZipImportError: cant decompress data; zlib not available少了zlib1g-dev库按前面的依赖列表装齐就解决了。这三个报错是入门必踩我把它放在最前面是希望你别在这些地方浪费时间。4.2 pip与包管理相关的经典问题问题装到了“别的Python”里pip install requests之后写脚本import requests却报ModuleNotFoundError。这个我猜所有人都遇到过。排查思路很简单先看当前pip --version指向哪个解释器再对比当前python --version指向哪个解释器如果不一致就用python -m pip install requests来确保装到当前python对应的环境里。问题Python 2.7环境里pip升级后不可用Python 2.7自带的pip版本很老直接pip install --upgrade pip可能升到最新版但最新版pip已经不支持Python 2了升级完了会直接报语法错误无法运行。正确做法是升级到支持Python 2的最后一个版本pip install --upgrade pip21。这个问题很隐蔽我当初帮人排查了好久才定位到是pip版本太新导致解释器不兼容。问题No matching distribution found for requests这个一般是pip源里没有当前平台对应的安装包或者pip版本太老认不出新格式的wheel包。先升级pip再确认源配置正确。Python 2.7环境特别容易遇到因为很多新包已经不再发布支持Python 2的版本了这种情况只能从requirements.txt里锁定旧版本号。4.3 node-gyp、工具链与系统级兼容问题问题npm安装node-sass等原生模块时报python2 not found很多Node.js的原生模块在编译时需要Python 2作为构建脚本的解释器比如node-sass、node-gyp。系统里如果没有python2命令构建就会失败。解决办法是在~/.npmrc里指定python/root/.pyenv/versions/2.7.18/bin/python或者安装时直接传参npm install --python/root/.pyenv/versions/2.7.18/bin/python。这个坑在维护老前端项目时非常常见配置好之后一劳永逸。问题/usr/bin/env: python: No such file or directory一些老脚本的shebang写的是#!/usr/bin/env python系统里没有python这个命令时就会报这个错。我用update-alternatives或者直接建软链接解决sudo ln -s /root/.pyenv/versions/2.7.18/bin/python /usr/local/bin/python。但这里要非常小心不要覆盖系统自带的python3命令也不要在系统级傻傻地把python指向2.7然后期望它同时兼容3.x这样只会造成更大的混乱。问题shell初始化时pyenv报错pyenv: command not found这种基本是写环境变量的位置不对或者当前shell是zsh但你改的却是.bashrc。用echo $SHELL先确认当前shell类型zsh就用~/.zshrcbash就用~/.bashrc改完记得source或者新开会话。4.4 排查问题的方法论三步定位法不管遇到什么诡异的问题我排查的思路都是三句话先看版本再看路径最后才怀疑依赖。第一步看python --version和pip --version是否一致第二步看which python的实际路径对不对是不是指向预期版本第三步看关键依赖是否装好用python -c import ssl; print(ssl.OPENSSL_VERSION)验证。版本对了、路径对了90%的问题都能定位出来剩下10%才是依赖和编译层面的问题。5. 进阶扩展离线安装、环境迁移与超高效率技巧5.1 离线环境安装多版本Python的完整链路不少生产服务器在内网隔离区没法直接访问外网。这种环境下用pyenv安装Python的思路要变一下。首先在一台能联网的机器上先创建~/.pyenv/cache目录然后用pyenv install把需要的版本装一遍装好之后到~/.pyenv/versions目录把对应的版本目录打包。也可以只下载源码包放到离线机器的~/.pyenv/cache目录下再执行pyenv installpyenv检测到缓存存在就不会再联网。第三方依赖包的离线安装可以参考这个思路先用联网机器创建虚拟环境再pip download -r requirements.txt -d /tmp/packages把包全部下下来拷到离线机器后pip install -r requirements.txt --no-index --find-links/tmp/packages这样pip就不走网络只从本地目录找包。顺便说一句Python 2.7的源码包在官方仓库已经处于归档状态某些老版本可能找不到下载地址如果pyenv install报了下载失败去~/.pyenv/cache里手动放一份源码包是最省心的方案。5.2 环境迁移与团队协作的最佳实践团队里多人开发最怕“在我机器上是好的”这种问题。用pyenv .python-version可以有效缓解。项目里提交.python-version文件别人clone下来进入目录就会自动切换对应的Python版本或虚拟环境然后装依赖即可基本没有版本不一致的问题。环境迁移时项目依赖清单一定要用pip freeze或pipreqs生成避免手工维护由于漏装导致环境不完整。pip freeze会把当前环境所有包导出来包括很多间接依赖好处是环境还原度高坏处是PyPI上某几个老包可能已经被下架安装时会报404。这时候就需要手工从源码包安装或者从已有环境里打包site-packages目录整个移植这个办法虽说土了点但效果其实很好。5.3 提高效率让命令少敲一半的小技巧日常开发中来回切目录、频繁输pyenv local其实也够烦的。我在~/.bashrc里配了几个别名和函数alias py2pyenv local legacy-env alias py3pyenv local newapi-env function pyenv-activate() { local venv_name$1 pyenv activate $venv_name }配合pyenv-virtualenv的自动激活功能每次进入项目目录终端提示符前面会出现当前虚拟环境名一眼就知道自己处于哪个环境不会再出现“我以为我在项目A里结果装包装到了项目B”的尴尬。6. 写在最后的几句大实话Python 2和Python 3多版本共存这件事本质上没有多高深的技术含量它就是一套“分层隔离”思想的实践解释器归pyenv管第三方包归venv管项目环境归.python-version管每一层只做一件事而且只做自己该做的那件事。很多人把它搞复杂是因为总想用一把锤子解决所有问题要么只切软链接、要么只用虚拟环境结果版本乱了、包也乱了最后只能重装系统。我个人在实际操作中还有一条自己的原则永远不要动系统自带的Python。系统Python是给apt和系统工具用的你强行换掉它的版本轻则某些系统命令出问题重则整个系统桌面或服务都可能崩掉。所有业务代码、工具、虚拟环境一律放到pyenv管理的目录下这样整个环境的可控性和可回溯性都高很多。最后再分享一个小技巧如果你维护着多个老项目建议把每个人项目的.python-version文件内容记下来顺便用pyenv install --list里的版本号标注一下当前项目可用的版本。以后遇到同事问你“这个项目是用哪个版本跑的”你就不用翻聊天记录了一个命令cat .python-version就搞定。环境统一了沟通成本直线下降这才是多版本共存方案真正的价值所在。
