Python 开发环境配置 - 码剑客

配置 Python 开发环境：Windows 官方安装器与 py launcher、pyenv/uv 多版本管理、虚拟环境、pip 换源、工程创建与常见报错排查。

Python 3.11 / 3.12更新于 2026-10-29共 28 条

安装与版本管理

Windows 上安装 Python 3.12，安装器会同时提供 py 启动器

winget install Python.Python.3.12

用官方安装包时务必勾选 Add python.exe to PATH，否则命令行找不到 python

macOS 用 Homebrew、Ubuntu 用 apt 安装指定版本与 venv 模块

# macOS
brew install python@3.12
# Ubuntu / Debian
sudo apt update && sudo apt install -y python3.12 python3.12-venv python3-pip

Windows 列出本机已安装的全部 Python 版本与路径

py -0p

多版本共存时用 py -3.11、py -3.12 显式指定解释器

用 pipx 安装 uv，uv 可同时管理 Python 版本、虚拟环境与依赖，速度远超 pip

pip install --user pipx
pipx install uv

用 uv 安装并列出可用的 Python 版本，无需管理员权限

uv python install 3.12
uv python list

全局切换 pip 到清华源，并确认配置已写入

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config list

只对本次安装临时指定镜像源，不修改全局配置

pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

内网源使用 HTTP 或自签证书时，把地址加入信任列表

pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

macOS/Linux 通过环境变量让 pip 走代理，Windows 用 set 同名列

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

uv 同样支持指定索引源，可由 UV_INDEX_URL 环境变量统一设置

uv pip install requests --index-url https://pypi.tuna.tsinghua.edu.cn/simple

在项目内创建并激活虚拟环境，避免污染全局依赖

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

每个项目独立 .venv，并把 .venv/ 加入 .gitignore

确认当前 shell 实际使用的解释器路径，虚拟环境激活后应指向 .venv

where python
# macOS / Linux
which python3

开启 UTF-8 模式，规避 Windows 下中文读写乱码

# Windows PowerShell（永久）
[Environment]::SetEnvironmentVariable("PYTHONUTF8", "1", "User")
# macOS / Linux
echo 'export PYTHONUTF8=1' >> ~/.zshrc

退出当前虚拟环境，回到系统解释器

deactivate

验证解释器与 pip 是否指向同一环境，并查看已装依赖

python --version
pip --version
pip list

创建最小工程、安装依赖并验证可正常导入

mkdir demo && cd demo
python -m venv .venv
pip install requests
python -c "import requests; print(requests.__version__)"

导出与还原依赖清单，用于交接与部署

pip freeze > requirements.txt
pip install -r requirements.txt

用 uv 初始化工程、添加依赖并运行，无需手动激活虚拟环境

uv init demo
cd demo
uv add requests
uv run main.py

临时起一个静态文件服务器，快速验证脚本产出的页面

python -m http.server 8000

安装 Python 官方扩展、类型提示与 Ruff 格式化/静态检查

code --install-extension ms-python.python
code --install-extension ms-python.vscode-pylance
code --install-extension charliermarsh.ruff

命令行安装格式化与类型检查工具，便于接入 CI

pip install ruff black mypy

需要交互式分析时安装并启动 JupyterLab

pip install jupyterlab
jupyter lab

PowerShell 禁止激活脚本时，放宽当前用户执行策略后再激活虚拟环境

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

用 python -m pip 方式升级 pip，避免多环境装错位置

python -m pip install --upgrade pip

编译类依赖安装失败时，先升级构建工具链再重试

pip install --upgrade pip setuptools wheel

遇到 command not found 时逐个排查 PATH 中可见的解释器

where python3
where py

依赖包下载损坏或磁盘占用过大时清理 pip 缓存

pip cache purge

检查已安装依赖之间的版本冲突

pip check