Python 开发环境与包管理

Python 的安装

Windows

下载安装包，推荐使用清华开源软件镜像站下载

​​

以 python-3.13.9-amd64.exe 为例，Python 版本 3.13.9

安装 tips：

• 勾选最下面 "Add Python 3.x to PATH" 将 Python 配置到环境变量（用户机环境变量）

• 然点 "Customize installation"，建议全勾
• 安装路径选择自己日常存放开发环境 SDK 的目录

配置环境变量：

当安装时没有勾选 Add to PATH，则需要将安装目录、安装目录下的 Scripts 目录配置到环境变量。

使用命令检查是否安装成功：

python -V
pip -V

​​

配置 pip 国内镜像：

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

​​

Linux

以 Debian 为例：

sudo apt update
# 直接装官方仓库版（可能不是最新）
sudo apt install python3 python3-pip python3-venv

注意事项：在早前版本的 Ubuntu/Debian 中，禁止使用 sudo pip install​ 而没有禁止用户级的 install（通常安装到 ~/.local/lib/python3.x/site-packages 目录）。

从 Ubuntu 23.04（及 Debian 12）开始强制执执行 PEP 668 保护机制，禁止用户使用系统级 Python 执行 pip install​ 操作，建议通过虚拟环境隔离安装。

虚拟环境

虚拟环境是什么

在众多编程语言，依赖隔离是一个老生常谈的问题。拿 Java 来说，Java 默认使用本地的全局仓库，需要在项目中使用 maven / gradle 构建工具声明好需要的依赖版本。相比之下，NodeJs 是天生的项目级隔离，除非强行指定全局安装，否则所有依赖都被安装到当前项目的 node_modules​ 目录下，当种处理方式会导致一份依赖在不同项目占用多份空间，因此也催生了一些包管理工具，如 PNPM，利用 全局缓存 + 硬链接​ 实现节约磁盘和避免重复下载的目的。

Python 官方默认提供了虚拟环境工具 venv，在不同场景一些社区也有其他的解决方案，如 conda 等，在纯 Python 开发

为什么需要虚拟环境

在一个环境中，一个依赖的安装不同版本，后者会覆盖前者，只会存在一个版本，这会导致一个环境下的多个项目依赖的版本不同而导致冲突，所以需要进行依赖环境的隔离。

其次，一些操作系统默认自带了 Python 环境，且禁止了用户在全局环境中安装包，防止破坏操作系统稳定性，因此必须创建虚拟环境来使用

使用 venv

Python 3.3+ 内置了 venv，创建虚拟环境的命令：

# 创建
python -m venv .venv

# 激活（Linux/macOS）
source .venv/bin/activate
# Windows
.venv\Scripts\activate

# 验证
which python  # 指向 .venv/bin/python
pip list      # 只有 2 个包：pip setuptools

# 退出
deactivate

在当前项目的 .venv 目录下，使用 Scripts​ 目录下的 activate 脚本激活当前虚拟环境，后续使用 pip​ 安装依赖，都将存放到 Lib/site-packages​ 目录，推荐使用 python -m pip​ 来执行 pip 命令，这样指定 Python 解释器可以防止由于环境变量优先级问题而导致使用其他环境的 pip。

包管理

pip

Python 自带的 pip 包管理工具，常用命令如下：

# 安装
pip install requests==2.31.0

# 升级
pip install -U requests

# 卸载
pip uninstall requests -y

# 查看
pip show requests

pip 复现依赖的方法：

# 生成
pip freeze > requirements.txt

# 恢复
pip install -r requirements.txt

pip freeze 会列出有已安装的依赖及版本

​​

可以看到安装 requests 库，同时自动安装了它依赖的其他库，所以通过导出的 requirements.txt​ 文件，可以快速复现一个项目的开发场景。

问题是当我们不在需要 requests 库时，执行 pip uninstall requests​ 卸载 requests 库后，发现由它而引入的其他库并没有被移除，也就说 pip 无法正确处理直接依赖和间接依赖。

对于那些由于成为孤儿的间接依赖，官方给出的解决方案是使用 pyproject.toml​。

​pyproject.toml​ 是官方推出的 Python 项目配置表，用于统一各大工具的配置文件，目前很多工具都已经陆续支持。

在 toml 中维护只需要维护好直接依赖版本

[project]
name = "learn-python"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "requests>=2.32.5",
]

pip 23+ 支持从 pyproject.toml​ 安装依赖

pip install .
# 或
pip install -e . 

需要注意的是 pip install .​ 会执行构建 + 安装​ 两个过程，会把本地代码直接打进 site-packages 目录，对于频繁修改的本地文件来说多有不便。

推荐使用 pip install -e .​ 来安装依赖，会在 site-packages 目录中链接文件，指向本地代码，从而编辑修改能及时生效

uv

pip 命令能从 pyproject.toml​ 中读取依赖，但目前不能方便的将依赖配置到 toml 中，推荐使用更加强大的 uv 命令。

uv 是一个用 Rust 编写的极速 Python 包和项目管理工具。

uv 的安装：

方法 1：官方安装脚本

curl -LsSf https://astral.sh/uv/install.sh | sh

方法 2：Github Releases 下载安装文件

方法 3：直接使用 pip 安装

pip install uv

常用命令：

虚拟环境操作：

# 新建虚拟环境（默认目录 .venv）
uv venv

# 指定 Python 版本（自动下载若本地没有）
uv venv --python 3.11
uv venv py38 -p 3.8        # 自定义目录名

依赖管理：

# 初始化项目
uv init myproj

# 安装全部依赖并生成/更新锁文件
uv sync

# 仅更新锁文件（不实际装包，适合 CI 校验）
uv lock

# 升级单个包并重新锁定
# 锁文件会更新为最新兼容版本，其余包保持不动。
uv lock --upgrade-package pandas

# 添加运行时依赖
# 自动向 pyproject.toml 的 [project]dependencies 写入版本区间
uv add requests>=2.31

# 添加开发依赖
# 在 pyproject.toml 新增 [dependency-groups] dev = ["pytest"]
uv add --group dev pytest

# 移除依赖
uv remove requests

# 从旧 requirements.txt 批量导入
uv add -r requirements.txt

运行脚本：

# 直接执行 py 文件
uv run main.py
# 指定解释器
uv run python main.py
# 指定解释器版本，不存在将下载
uv run --python 3.12 main.py

兼容 pip 命令(90%+)：

# 把 pip 直接换成 uv pip，速度提升 10+ 倍
uv pip install requests
uv pip install -r requirements.txt
uv pip uninstall requests

还原依赖环境

当参与一个已存在的 Python 项目，如何快速还原开发环境？

场景 1：当项目使用 pyproject toml 文件来管理

• 使用 uv，直接 uv sync

• 使用 pip，使用 pip install .

场景 2：当项目使用 requirements.txt 管理

• pip install -r 或 uv pip install -r 直接安装依赖
• uv add -r 可以将 requirements 内容配置到 pyproject toml