Python管理工具：包、版本、环境

概述

注：Python开发者应该没有不犯选择困难症的。本文目前仅仅是梳理汇总，并提供官方中英文文档，方便快速链接学习；部分工具简单使用，有待进一步深入实践，记录遇到的问题。后面如果有时间会丰富内容，并考虑拆分成上中下多篇。

Python的管理涉及诸多方面：

包管理：Package Management，
版本管理：Version Management，
环境管理：Environmental Management，venv（内置）、virtualenv、Pipenv
包发布：Package Publish
包构建：Package Build

图片来自文末参考。

PyPA

开正片之前，不得提一下PyPA这个开源组织。

全称Python Packaging Authority，即Python打包权威组织，官方维护Python打包生态的工作组，主要负责制定标准、开发与维护核心工具，解决生态混乱问题。

推出工具链：

类别	项目/格式	核心作用
核心构建与分发	setuptools	最传统和广泛使用的构建后端
	flit	为纯Python包设计的轻量、简单的构建工具
	hatch	功能丰富的现代化项目管理与构建工具
	build	符合PE P517标准的独立包构建前端
	wheel	二进制包格式标准，取代旧的`.egg`格式
依赖与环境管理	pip	Python官方包安装器，生态基石
	virtualenv	创建隔离Python环境的事实标准工具
	pipenv	旨在整合包管理与虚拟环境管理，使用`Pipfile`
	pipx	专为安全、隔离地安装和运行Python命令行应用而设计
	pipfile	依赖声明文件格式，旨在替代`requirements.txt`
发布与持续集成	twine	安全地将构建好的包上传到PyPI的工具
	cibuildwheel	在CI中跨平台构建标准的`wheel`二进制包
仓库与索引	bandersnatch	PyPI的镜像客户端，用于创建私有镜像

PyPA相关组织

PSF：Python软件基金会；
PyPI：Python Package Index，Python包索引，Python官方软件仓库。PyPI的后端实现叫做warehouse；PyPI本身由PSF拥有和运营。

对于个人项目或团队选型，建议路径：

从标准开始：掌握pip+venv+requirements.txt+setuptools这一最广泛支持问题最少的工具链；
按需探索：当感到现有工具在某个环节成为瓶颈时，再去了解hatch+poetry+pdm+pipx等针对性更强的工具；
直接上手uv？

uv

GitHub，74.5K Star，2.3K Fork。参考uv使用与实战。

Pyenv

开源（GitHub，43.8K Star，3.2K Fork）Python版本管理工具，官方文档。

Poetry

官网，开源（GitHub，34.1K Star，2.4K Fork），官方文档

Pipenv

官网，开源（GitHub，25.1K Star，1.9K Fork）包管理与虚拟环境管理工具。

安装：pip install pipenv

命令行使用：

bash 复制代码

pipenv install # 初始化虚拟环境，生成2个文件：Pipfile和Pipfile.lock

Pipfile文件示例：

复制代码

[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[packages]

[dev-packages]

[requires]
python_version = "3.12"

Pipfile.lock文件示例：

json 复制代码

{
    "_meta": {
        "hash": {
            "sha256": "702ad05de9bc9de99a4807c8dde1686f31e0041d7b5f6f6b74861195a52110f5"
        },
        "pipfile-spec": 6,
        "requires": {
            "python_version": "3.12"
        },
        "sources": [
            {
                "name": "pypi",
                "url": "https://pypi.org/simple",
                "verify_ssl": true
            }
        ]
    },
    "default": {},
    "develop": {}
}

命令行使用：

bash 复制代码

pipenv --where # 列出本地工程路径
pipenv --venv # 列出虚拟环境路径
pipenv --py # 列出虚拟环境的Python可执行文件
pipenv install # 安装包，即创建虚拟环境
pipenv install moduel --dev # 在开发环境安装包
pipenv graph # 查看包依赖
pipenv lock # 生成lockfile
pipenv install --dev # 安装所有开发环境包
pipenv uninstall --all # 卸载所有包
pipenv --rm # 删除虚拟环境
pipenv run python xxx.py # 虚拟环境运行python
pipenv --rm # 删除虚拟环境
pipenv uninstall 包名 # 删除部分包

py 复制代码

Nuitka

官网，开源（GitHub，14.2K Star，748 Fork），官方文档，中文文档，Nuitka中文指南，知乎专栏。

pipx

开源（GitHub，12.3K Star，503 Fork），官方文档

pip

开源（GitHub，10K Star，3.2K Fork）包安装工具，官方文档。

参考pip实战与问题记录。

PDM

官网，开源（GitHub，8.5K Star，459 Fork），Python Development Master简写，遵循最新PEP(Python Enhancement Proposals)标准，新一代Python包和依赖项管理器。超越简单的包安装功能，致力于在整个开发生命周期中提升效率和体验。继承传统工具的优点，更引入多项创新特性，旨在为Python开发者提供一个现代化、可靠且灵活的项目管理工作流程。

建议将PDM独立于应用程序安装成一个全局命令，以方便不同项目使用。

安装

bash 复制代码

# 安装pipx
python -m pip install --user --upgrade pip
python -m pip install --user pipx
python -m pipx ensurepath
pipx install pdm

pdm new myproject
# 或对已有项目
pdm init
# 国内镜像源
pdm config pypi.url https://mirrors.aliyun.com/pypi/simple/
# 查看配置
pdm config
# 依赖管理
pdm add Flask==2.0.1 # 指定精确版本
pdm add Django~=4.0 # 指定版本范围：[4.0.0,4.1.0)
pdm add numpy>=1.20 # 指定最低版本
pdm remove Flask
# 显示特定包的详细信息，包括其版本、安装路径、依赖项等
pdm show
# 以树状图的形式展示依赖关系
pdm list --graph
# 根据pyproject.toml配置解析依赖并安装，同时将依赖关系写入pdm.lock锁文件
pdm install
# 根据pdm.lock依赖锁文件复原完整的运行环境
pdm sync
# 运行
pdm run python main.py
pdm run pytest

创建pyproject.toml，相当于Node.js项目的package.json文件。.pdm-python，指定当前项目使用的Python解释器路径，即之前创建的虚拟环境，建议不要加入Git管理。

添加开发依赖：对于仅在开发或测试阶段需要的依赖，可使用-d或--dev标志将其作为开发依赖添加。开发依赖会添加到 pyproject.toml 的 [tool.pdm.dev-dependencies] 部分。pdm add pytest --dev。

说明文档：编辑 pyproject.toml 文件，添加一个 docs = [] 的占位符，执行命令：pdm add pytest -G docs

代码质量：使用Ruff进行代码格式化和Lint检查，执行以下命令前需先配置规则：

toml 复制代码

[tool.ruff]
respect-gitignore = true
target-version = "py39"
line-length = 120
src = ["src"]

[tool.ruff.format]
quote-style = "single"

[tool.ruff.lint]
extend-select = [
"I",    # isort
"B",    # flake8-bugbear
"C4",   # flake8-comprehensions
"FA",   # flake8-future-annotations
"PGH",  # pygrep-hooks
"RUF",  # ruff
"W",    # pycodestyle
"UP",   # pyupgrade
"YTT",  # flake8-2020
]
extend-ignore = ["B018", "B019", "RUF018"]

执行命令：

bash 复制代码

pdm run ruff format . # 格式化代码
pdm run ruff check . --fix # lint检查

pyproject.toml 中[tool.pdm.scripts]定义命令别名，pdm run <alias_name> 来执行。

发布包到 PyPI：需要先在 https://pypi.org 注册账号，并完成相关的安全验证：

bash 复制代码

pdm config repository.pypi.url https://upload.pypi.org/legacy/
pdm config repository.pypi.username __token__
pdm config repository.pypi.password pypi-<your_token>

执行pdm publish。

hatch

开源（GitHub，7K Star，355 Fork）项目管理工具，官方文档。

pyenv-win

开源（GitHub，6.8K Star，555 Fork）版本管理工具，官方文档。pyenv的Windows版本，两个独立实现的项目，核心功能都是管理多个Python版本。

特性维度	pyenv	pyenv-win
目标平台	Linux和macOS等类Unix系统	Windows
起源	原始项目	为在Windows上实现类似功能而创建的独立项目，通常被称为`fork`或Windows移植版
工作原理	通过`shims`机制拦截命令并重定向路径	实现类似的功能以适应Windows环境
与虚拟环境集成	可通过`pyenv-virtualenv`插件管理	可通过`pyenv-win-venv`扩展管理（与`pyenv-virtualenv`不兼容）

virtualenv

开源（GitHub，5K Star，1.1K Fork），官方文档。

Invoke

开源（GitHub，4.6K Star，381 Fork），官方文档。Invoke是Fabric（自动化发布、远程部署工具）中的最核心基础组件；作为一个命令行工具，invoke专注于任务执行。

安装：pip install invoke

示例：

py 复制代码

from invoke import task

@task
def greet(c, name):
	c.run(f"echo {name}加油!")

执行

解读：

使用@task装饰器标记某个函数为一个任务；
上下文参数c必须显式指明，缺少这个参数则抛出异常；其他参数如name可有可无；
和常规.py文件不同，不能使用python xx.py来执行；
文件名为invoke_task.py或task.py，invoke命令提示找不到，必须要重命名为tasks.py；
inv func_name param_name等价于invoke func_name param_name。

进阶

交互式操作

在某些场景中存在需要人参与并确认的操作，Invoke提供这种能力。通过监听stdout和stderr，支持在stdin中输入必要的信息。

py 复制代码

tox

开源（GitHub，3.8K Star，539 Fork），官方文档。

Command line driven CI frontend and development task automation tool

支持创建隔离的Python环境，安装不同版本的Python解释器与各种依赖库，方便开发者做自动化测试、打包、持续集成。

bash 复制代码

E:\Python\code>tox
ROOT: No loadable tox.ini or setup.cfg or pyproject.toml or tox.toml found, assuming empty tox.ini at E:\Python\code
  py: OK (1.81 seconds)
  congratulations :) (2.42 seconds)

配置文件：

tox.ini：版本后不建议
setup.cfg：
pyproject.toml：
tox.toml：

定制自定义插件，参考：https://tox.wiki/en/latest/plugins.html

插件生态

tox创建/管理虚拟环境只是为了方便测试？因此相比其它可管理虚拟环境的工具，如 Virtualenvwrapper、conda、pipenv、poetry，它在某些方面就存在着不足。

pipfile

开源（GitHub，3.2K Star，152 Fork）

setuptools

官网，开源（GitHub，2.8K Star，1.3K Fork）Python打包分发的事实标准工具。用于创建、分发和安装Python包；扩展Python标准库中的distutils，使其更易于使用和扩展，并提供额外功能，如自动解决依赖关系和插件系统。

Python库的打包分发方式有两种：

源码包：source dist，sdist，如.zip、.tar.gz
二进制包：binary dist，bdist，不用再编译，安装更快，如.egg、.whl、.rpm、.wininst。

安装：pip install setuptools

创建setup.py文件，示例：

py 复制代码

# A sample distutils script to show to build your own extension module which extends pywintypes or pythoncom.
# Use 'python -m build' to build this extension.
import os
from setuptools import Extension, setup, find_packages
from sysconfig import get_paths

sources = ["win32_extension.cpp"]
lib_dir = get_paths()["platlib"]
# Specify the directory where the PyWin32 .h and .lib files are installed.
# If you are doing a win32com extension, you will also need to add win32com\Include and win32com\Libs.
ext = Extension(
	"win32_extension",
	sources,
	include_dirs=[os.path.join(lib_dir, "win32", "include")],
	library_dirs=[os.path.join(lib_dir, "win32", "libs")],
)
setup(
	name="win32 extension sample",
	version="0.1",
	ext_modules=[ext],
	author='your name',
	description='Your library description',
	packages=find_packages(),
	install_requires=[
		'dependency1',
		'dependency2'
	]
)

解读：find_packages()可自动查找库中的所有包，install_requires参数指定库所依赖的其他包。

python setup.py sdist：打包成源码包sdist。不指定格式，sdist会根据当前平台创建默认格式；在类Unix平台上，将创建后缀名为.tar.gz分发包，在Windows上为.zip文件。--formats=gztar参数可以指定文件格式。

python setup.py install：安装源码包，先解压缩，再执行setup.py。

打包二进制包：

python setup.py bdist --format=wheel：等价于python setup.py build_wheel、python setup.py bdist_wheel，其他类推；
python setup.py bdist_wininst：得到Windows平台下可执行exe安装文件；

pip install xxx.whl：安装二进制包，

cibuildwheel

开源（GitHub，2.2K Star，295 Fork）

flit

将Python包和模块发布到PyPI的开源（GitHub，2.2K Star，151 Fork）工具，官方文档，中文文档。

安装：pip install flit

命令行使用：

bash 复制代码

flit init # 初始化，用于生成pyproject.toml文件
flit install 
flit build
flit publish # 发布
python3 -m flit.tomlify # 旧版本Flit使用flit.ini文件，运行此命令转换为pyproject.toml

pyproject.toml文件示例：

bash 复制代码

[build-system]
requires = ["flit_core >=3.11,<4"]
build-backend = "flit_core.buildapi"

[project]
name = "dddd"
authors = [{name = "johnny", email = "johnny@qq.com"}]
license = "MIT"
license-files = ["LICENSE"]
dynamic = ["version", "description"]

bash 复制代码

PyBuilder

官网，开源（GitHub，1.9K Star，269 Fork）构建工具，基于依赖的插件系统，类似于Maven。

生态和社区规模不如poetry、tox。

优点：

全Python：无需额外配置JVM、Node环境
插件化：官方插件覆盖常用需求，支持自定义插件
配置即代码：使用Python编写构建脚本，灵活度高
兼容多版本：支持3.9‑3.13版本以及PyPy

缺点：

生态相对小：相比invoke、tox插件数量少一点
学习曲线：首次接触时要搞懂得build.py的结构
文档散乱：官方文档有点分散，需要自行搜罗例子
社区活跃度：相对更热门的工具（如Poetry）社区稍弱

功能	说明	典型插件
依赖管理	自动下载、解析`requirements.txt`，保证环境一致	`python.install_dependencies`
单元测试	集成`unittest`、`pytest`，跑完自动生成报告	`python.unittest`、`python.pytest`
代码覆盖率	统计覆盖率，生成HTML报告	`python.coverage`
文档生成	支持Sphinx，一键生成API文档	`python.sphinx`
打包发布	生成`sdist`、`wheel`，直接推到PyPI	`python.distutils`、`python.pypi，`
自定义任务	用Python写自定义Task，随心所欲	`core`插件提供API

安装

bash 复制代码

pip install pybuilder
# pre-release版本
pip install --pre pybuilder

然后得到可执行命令pyb，项目根目录build.py示例：

py 复制代码

from pybuilder.core import use_plugin, init
# 必装插件
use_plugin("python.core")
use_plugin("python.unittest")
use_plugin("python.coverage")
use_plugin("python.distutils")
# 默认任务：执行完所有步骤后直接publish，发布到PyPI
default_task = "publish"

命令使用：

bash 复制代码

# 清除缓存
pyb clean
pyb install
# 测试
pyb run_unit_tests
# 覆盖率报告
pyb coverage_report

使用流程

步骤	操作	说明
初始化	`pyb init`（可选）	生成默认目录结构`src/main/python`、`src/unittest/python`
编写插件	在`build.py`里`use_plugin`	只要插件在`pybuilder.plugins`里能被调到就行
定义属性	`@init`装饰函数里`project.set_property`	比如`project.set_property('dir_source_main_python', 'my_pkg')`
运行任务	`pyb <task>`	常用任务：`clean`、`install_dependencies`、`run_unit_tests`、`publish`
CI集成	把`pyb install`加入`.github/workflows`或Jenkins	自动化构建，代码一推就跑完整流程

twine

开源（GitHub，1.7K Star，325 Fork），官方文档。

PyPy

开源（GitHub，1.5K Star，86 Fork），官方文档。

Python是纯解释执行字节码，导致运行速度相对较慢，PyPy旨在解决这一问题。一个用Python的子集（RPython）编写的Python解释器。

安装：下载链接提供各主流系统安装程序。不过只有Python 2.7和3.11两个版本。以Windows为例，下载zip包，解压缩，添加到系统环境变量，即可使用pypy3。

nox

开源（GitHub，1.5K Star，172 Fork）测试自动化工具，官方文档。

py2exe

build

参考

可能是最全的Python环境管理工具对比