Python环境配置

Python环境配置，包括传统方式和现代 uv 工具链配置

#dev #python #python #howto #growing

[!info] related notes

所属 MOC: Python MOC, 开发环境 MOC

相关工具: uv, ruff, pylance

关系笔记: python-package-management-evolution

Python环境配置

Windows：已有 Scoop 时安装 Python

python 本体

# 安装最新稳定版 Python（会自动添加到 PATH） 
scoop install python 

# 查看额外版本清单后再按项目约束选择
scoop bucket add versions
scoop search python

旧命令 scoop install python39 来自 versions bucket，目前对应旧的 3.9.13 安装包；仅用于需要该历史环境的项目，不把它当作当前受维护版本的推荐。

可选工具的职责

[!info] tip 现在推荐直接使用 uv，见下方

# 安装 pipenv（虚拟环境 + 依赖管理）
scoop install pipenv

# 安装 poetry（现代依赖管理工具，支持虚拟环境）
scoop install poetry

# 安装 pyenv-win（Python 版本管理器，配合 scoop 使用更灵活）
scoop install pyenv-win

pipenv/Poetry 管项目依赖与环境，pyenv-win 管解释器版本；按项目需要选择，不要求全部安装。

pyenv 使用（保留旧项目示例）

以下 3.10.11 是原记录中的历史版本；新项目应从列表中选择依赖支持的受维护版本。

# 查看可安装的 Python 版本
pyenv install --list

# 安装指定版本
pyenv install 3.10.11

# 为当前项目设置本地版本
pyenv local 3.10.11

# 查看当前生效版本
pyenv version

Vscode

微软（Microsoft）官方提供的 Python 核心扩展家族。微软近年来将原本臃肿的单一 Python 插件拆分成了一系列模块化的插件，以提高性能和稳定性。

以下是几个 Python 相关插件的具体作用：

Python (核心基础插件)
- 作用：这是 VS Code 中最基础的 Python 插件。它提供了 Python 开发的整体框架支持，相当于一个“入口”。它提供解释器选择、测试集成与运行入口；格式化由 Ruff、Black 等独立扩展负责。
Pylance (语言服务器 / 智能提示)
- 作用：这是你的“代码大脑”。Pylance 是一个高性能的语言服务器，专门负责智能代码补全（IntelliSense）。当你敲击代码时弹出的函数提示、参数说明、变量类型检查、自动导入（Auto-import）以及代码跳转（Go to Definition）等功能，全都是它的功劳。
Python Debugger (代码调试器)
- 作用：专门负责找 Bug 和调试代码。它基于 debugpy 构建，让你可以在 VS Code 中设置断点、单步执行代码（F5/F10/F11）、监控变量在运行时的实时状态。这个功能以前包含在核心的 Python 插件中，现在被独立出来以便单独更新。
Python Environments (环境管理器)
- 作用：专门负责管理你的 Python 运行环境。在 Python 开发中，我们经常使用虚拟环境（如 venv, conda, poetry 等）来隔离项目依赖。这个插件可以自动扫描并帮助你在右下角快速切换当前项目所使用的解释器和虚拟环境。

uv 与 VS Code 集成（推荐方案）

现代 Python 开发推荐使用 uv 作为工具链，配合 VS Code 的 Python 插件家族。

下面沿用本库的 uv 工作流；已有 Poetry/Pipenv 项目先遵循项目契约，不因编辑器配置就迁移依赖管理。

工具分工

工具	职责
uv	环境管理、包管理、Python 版本管理
Pylance	代码补全、类型检查、代码导航
Ruff	代码格式化、Linting 检查

完整配置

先创建项目环境，再在项目根目录的 .vscode/settings.json 中添加：

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "basic",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll.ruff": "explicit",
      "source.organizeImports.ruff": "explicit"
    }
  }
}

Windows 用户使用：

{
  "python.defaultInterpreterPath": "${workspaceFolder}\\.venv\\Scripts\\python.exe"
}

defaultInterpreterPath 是初始默认值；若工作区已选过解释器，修改此设置不一定切换它。使用 Python: Select Interpreter 核对，并在终端打印 sys.executable 验证。

插件选择建议

保留的插件：

VS Code 官方 Python 插件（Microsoft 出品）
Pylance（智能提示和类型检查）
Ruff 插件（代码格式化和检查）

Poetry/Pipenv 或第三方环境 UI 扩展是否保留取决于所维护项目；确认没有项目依赖其功能后再移除。

使用流程

创建项目：uv init my-project，然后 cd my-project。
添加依赖：uv add requests；需要恢复已有环境时执行 uv sync。
用 code . 打开该目录；在 Python: Select Interpreter 中确认项目 .venv。
执行 uv run python -c "import sys; print(sys.executable)"，检查路径与编辑器选择一致。

uv 的安装与项目命令见 uv-install-and-project-workflow；对象介绍见 uv。

参考：VS Code Python settings、Ruff editor integration。