WSL Ubuntu下Python3.13安装后Python3.12虚拟环境异常排查

一、Python3.13 旧项目依赖无法运行 #

• 旧项目依赖大多基于特定Python版本开发，3.13作为新版本，大概率存在依赖包版本不兼容（比如部分包还未适配3.13的语法或API变更）。
• 处理步骤：
  1. 给旧项目单独创建Python3.12的虚拟环境，避免和3.13的全局环境冲突。
  2. 打开项目的requirements.txt或pyproject.toml，逐个核对依赖包是否支持Python3.13，对不兼容的包指定适配3.12的版本号。

二、Python3.12 venv 在VS Code中的异常问题 #

1. VS Code提示“无效Python解释器” #

• 问题根源：VS Code的Python插件未正确识别WSL中venv的解释器路径，或者解释器的元数据损坏。
• 排查步骤：
  • 打开VS Code命令面板（Ctrl+Shift+P），执行Python: Select Interpreter，手动选择venv/bin/python3.12的路径，不要使用自动识别选项。
  • 检查VS Code的WSL扩展是否为最新版本，旧版本可能存在路径解析bug。
  • 删除项目根目录.vscode/settings.json中关于Python解释器的配置，重新选择后让插件自动生成配置。

2. 命令行激活venv后Pylance提示依赖无法解析 + 重装pip报错“ModuleNotFoundError: No module named 'pip'” #

• 问题根源：venv的pip路径被VS Code插件误识别，或者venv的site-packages目录权限异常、pip的入口脚本损坏。
• 排查步骤：
  1. 激活venv后，执行which pip，确认输出是venv/bin/pip，而非系统的/usr/bin/pip。如果不是，说明venv的环境变量未正确加载，重启终端或重新执行source venv/bin/activate。
  2. 手动修复venv中的pip：
     • 激活venv后，执行python3.12 -m pip install --upgrade --force-reinstall pip，强制将pip重新安装到当前venv。
     • 检查venv的bin目录下是否有pip、pip3、pip3.12这三个脚本，若缺失，执行python3.12 -m ensurepip --upgrade（Debian/Ubuntu禁用系统Python的ensurepip，但虚拟环境中的Python不受此限制）。
  3. 修复Pylance的依赖解析：
     • 打开VS Code命令面板，执行Python: Clear Cache and Reload Window，清除插件缓存后重新加载窗口。
     • 确认项目的.vscode/settings.json中添加了"python.analysis.extraPaths": ["${workspaceFolder}/venv/lib/python3.12/site-packages"]，让Pylance能正确定位依赖库。

3. 系统Python3.12的ensurepip提示禁用 #

• 这是Debian/Ubuntu的正常设置，为避免破坏系统包管理而禁用系统Python的ensurepip，但虚拟环境中的Python不受此限制，激活venv后使用python -m ensurepip完全有效。

内容的提问来源于stack exchange，提问作者Лев Базинов