Python項(xiàng)目打包與發(fā)布的三大工具(setuptools、Poetry、Flit)使用完全指南
引言：當(dāng)你的代碼值得被世界看見
每個 Python 開發(fā)者都有這樣的時刻——你寫了一個解決實(shí)際問題的工具，同事們用了都說好，你開始思考：能不能讓更多人用上它？
這就是打包與發(fā)布的起點(diǎn)。
但隨之而來的困惑往往讓人望而卻步：setup.py、pyproject.toml、MANIFEST.in、wheel、sdist……這些概念是什么？setuptools、Poetry、Flit 又該選哪個？如何把包發(fā)布到 PyPI？
我做了十幾年 Python 開發(fā)，親歷了從手寫 setup.py 到現(xiàn)代 pyproject.toml 的整個演變。今天這篇文章，就是我希望當(dāng)年入門時就能讀到的那篇指南——帶你從零到一，真正搞清楚 Python 打包這件事。
第一章：先理解"打包"究竟是什么
在動手之前，先建立清晰的概念模型。
1.1 為什么需要打包
你的項(xiàng)目目錄
├── mylib/
│ ├── __init__.py
│ ├── core.py
│ └── utils.py
├── tests/
├── README.md
└── requirements.txt
別人想用你的庫，直接復(fù)制文件夾？顯然不夠優(yōu)雅。打包解決了這些問題：
- 依賴聲明：我需要哪些第三方庫，版本是多少？
- 元數(shù)據(jù)：作者、版本號、許可證、描述……
- 分發(fā)格式：讓
pip install能直接安裝 - 命令行工具：如果你的包提供 CLI，如何注冊入口點(diǎn)？
1.2 兩種分發(fā)格式
發(fā)布產(chǎn)物
├── mylib-1.0.0.tar.gz ← sdist（源碼發(fā)行包）
└── mylib-1.0.0-py3-none-any.whl ← wheel（二進(jìn)制發(fā)行包）
- sdist：源碼包，安裝時需要在用戶機(jī)器上構(gòu)建
- wheel：預(yù)構(gòu)建包，安裝速度更快，是現(xiàn)代推薦格式
1.3 配置文件的演變
Python 打包配置的歷史時間線
2000s setup.py（純 Python 腳本，靈活但混亂）
│
2012 setup.cfg（聲明式配置，分離邏輯與元數(shù)據(jù)）
│
2016 PEP 518 提出 pyproject.toml（統(tǒng)一的配置標(biāo)準(zhǔn)）
│
2021+ pyproject.toml 成為主流，各工具紛紛支持
現(xiàn)在的最佳實(shí)踐：使用 pyproject.toml 作為主配置文件，告別 setup.py。
第二章：三大工具橫向?qū)Ρ?/h2>
2.1 Setuptools——老牌權(quán)威
適用場景：復(fù)雜項(xiàng)目、需要編譯擴(kuò)展（C/C++ 擴(kuò)展）、需要高度自定義構(gòu)建過程
# pyproject.toml（現(xiàn)代 setuptools 寫法）
[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.backends.legacy:build"
[project]
name = "myawesome-lib"
version = "1.0.0"
description = "一個很棒的 Python 庫"
readme = "README.md"
license = {text = "MIT"}
authors = [
{name = "Your Name", email = "you@example.com"}
]
requires-python = ">=3.8"
dependencies = [
"requests>=2.28.0",
"click>=8.0",
]
[project.optional-dependencies]
dev = ["pytest>=7.0", "black", "mypy"]
docs = ["sphinx", "sphinx-rtd-theme"]
[project.scripts]
mylib-cli = "mylib.cli:main"
[project.urls]
Homepage = "https://github.com/yourname/mylib"
Documentation = "https://mylib.readthedocs.io"
對應(yīng)的項(xiàng)目結(jié)構(gòu)：
myawesome-lib/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│ └── mylib/ ← 推薦 src 布局
│ ├── __init__.py
│ ├── core.py
│ └── cli.py
└── tests/
└── test_core.py
為什么推薦 src 布局？它能防止你在開發(fā)時意外導(dǎo)入本地未安裝版本，讓測試更加可靠。
優(yōu)點(diǎn)：生態(tài)最成熟，文檔豐富，支持所有復(fù)雜場景
缺點(diǎn)：配置項(xiàng)繁多，學(xué)習(xí)曲線稍陡，依賴管理需配合 pip-tools 等工具
2.2 Poetry——現(xiàn)代全能選手
適用場景：日常 Python 項(xiàng)目，既要管理依賴又要打包發(fā)布，追求開發(fā)體驗(yàn)
Poetry 是目前我最推薦的工具，原因很簡單：它把虛擬環(huán)境管理、依賴管理、打包發(fā)布整合成了一套流暢的工作流。
# 創(chuàng)建新項(xiàng)目
poetry new myawesome-lib
# 目錄結(jié)構(gòu)自動生成
myawesome-lib/
├── pyproject.toml
├── README.md
├── myawesome_lib/
│ └── __init__.py
└── tests/
└── __init__.py
生成的 pyproject.toml：
[tool.poetry]
name = "myawesome-lib"
version = "0.1.0"
description = "一個很棒的 Python 庫"
authors = ["Your Name <you@example.com>"]
readme = "README.md"
license = "MIT"
homepage = "https://github.com/yourname/myawesome-lib"
repository = "https://github.com/yourname/myawesome-lib"
keywords = ["python", "library"]
classifiers = [
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",
]
[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.28.0"
click = "^8.0"
[tool.poetry.group.dev.dependencies]
pytest = "^7.0"
black = "^23.0"
mypy = "^1.0"
[tool.poetry.scripts]
mylib-cli = "myawesome_lib.cli:main"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
核心工作流：
# 添加依賴（自動更新 pyproject.toml 和 poetry.lock） poetry add requests # 添加開發(fā)依賴 poetry add --group dev pytest black # 安裝所有依賴（包含 lock 文件確保版本一致） poetry install # 運(yùn)行項(xiàng)目內(nèi)命令 poetry run python main.py poetry run pytest # 構(gòu)建發(fā)行包 poetry build # 輸出：dist/myawesome_lib-0.1.0.tar.gz # dist/myawesome_lib-0.1.0-py3-none-any.whl # 發(fā)布到 PyPI（一鍵完成） poetry publish
依賴版本控制語義：
[tool.poetry.dependencies] requests = "^2.28.0" # 兼容 2.x，不升級到 3.x click = "~8.0.0" # 只允許補(bǔ)丁版本升級 numpy = ">=1.20,<2.0" # 區(qū)間限定 flask = "*" # 任意版本（不推薦）
優(yōu)點(diǎn)：一體化體驗(yàn)、lock 文件保證可復(fù)現(xiàn)、依賴解析強(qiáng)大、發(fā)布流程簡潔
缺點(diǎn)：不支持 C 擴(kuò)展編譯、相對較重（但絕大多數(shù)項(xiàng)目不需要編譯擴(kuò)展）
2.3 Flit——極簡主義者的選擇
適用場景：純 Python 庫、結(jié)構(gòu)簡單、希望配置盡量少
# pyproject.toml
[build-system]
requires = ["flit_core>=3.4"]
build-backend = "flit_core.buildapi"
[project]
name = "mylib"
dynamic = ["version", "description"] # 從代碼中讀取
readme = "README.md"
license = {file = "LICENSE"}
authors = [{name = "Your Name", email = "you@example.com"}]
requires-python = ">=3.8"
dependencies = ["requests"]
版本號和描述直接從模塊文件中讀?。?/p>
# mylib/__init__.py """一個極簡的 Python 庫。""" # 這是包的 description __version__ = "1.0.0" # 這是版本號
# 構(gòu)建 flit build # 發(fā)布 flit publish
優(yōu)點(diǎn)：配置極少，上手快，適合小型純 Python 包
缺點(diǎn)：功能有限，不做依賴管理，復(fù)雜項(xiàng)目力不從心
2.4 三者對比速查表
| 功能維度 | setuptools | Poetry | Flit |
|---|---|---|---|
| 虛擬環(huán)境管理 | ? | ? | ? |
| 依賴管理 | 需配合工具 | ? | ?（僅聲明） |
| lock 文件 | ? | ? | ? |
| C 擴(kuò)展支持 | ? | ? | ? |
| 打包發(fā)布 | ? | ? | ? |
| 配置復(fù)雜度 | 高 | 中 | 低 |
| 生態(tài)成熟度 | 最高 | 高 | 中 |
| 推薦場景 | 復(fù)雜/C擴(kuò)展 | 日常項(xiàng)目 | 極簡小包 |
我的選擇建議：
- 新項(xiàng)目、純 Python → Poetry（首選）
- 有 C/C++ 擴(kuò)展 → setuptools
- 極簡小工具，不需要依賴管理 → Flit
第三章：實(shí)戰(zhàn)——從零發(fā)布一個真實(shí)的包
3.1 項(xiàng)目實(shí)戰(zhàn)：發(fā)布一個命令行文件統(tǒng)計工具
我們以 Poetry 為例，完整走遍發(fā)布流程。
需求：統(tǒng)計目錄下各類型文件的數(shù)量和大小，支持命令行調(diào)用。
# 初始化項(xiàng)目 poetry new filestats cd filestats
實(shí)現(xiàn)核心功能：
# filestats/core.py
from pathlib import Path
from collections import defaultdict
from dataclasses import dataclass
@dataclass
class FileStats:
count: int = 0
total_size: int = 0
@property
def size_mb(self) -> float:
return self.total_size / (1024 * 1024)
def analyze_directory(
path: str | Path,
recursive: bool = True
) -> dict[str, FileStats]:
"""分析目錄中各類型文件的統(tǒng)計信息"""
root = Path(path)
if not root.exists():
raise FileNotFoundError(f"路徑不存在：{path}")
stats: dict[str, FileStats] = defaultdict(FileStats)
pattern = "**/*" if recursive else "*"
for file_path in root.glob(pattern):
if not file_path.is_file():
continue
suffix = file_path.suffix.lower() or "(無擴(kuò)展名)"
stats[suffix].count += 1
stats[suffix].total_size += file_path.stat().st_size
return dict(sorted(stats.items(), key=lambda x: x[1].count, reverse=True))
# filestats/cli.py
import click
from pathlib import Path
from .core import analyze_directory
@click.command()
@click.argument("path", default=".", type=click.Path(exists=True))
@click.option("--no-recursive", is_flag=True, help="不遞歸子目錄")
@click.option("--top", default=10, help="顯示前 N 種文件類型")
def main(path: str, no_recursive: bool, top: int) -> None:
"""統(tǒng)計目錄中各類型文件的數(shù)量和大小"""
try:
stats = analyze_directory(path, recursive=not no_recursive)
except FileNotFoundError as e:
click.echo(f"錯誤：{e}", err=True)
raise click.Abort()
click.echo(f"\n?? 分析路徑：{Path(path).resolve()}")
click.echo(f"{'擴(kuò)展名':<15} {'數(shù)量':>8} {'大小(MB)':>12}")
click.echo("-" * 38)
for ext, stat in list(stats.items())[:top]:
click.echo(f"{ext:<15} {stat.count:>8} {stat.size_mb:>11.2f}")
total_files = sum(s.count for s in stats.values())
click.echo(f"\n共計 {total_files} 個文件，{len(stats)} 種類型")
注冊 CLI 入口：
[tool.poetry.scripts] filestats = "filestats.cli:main"
本地測試：
poetry install poetry run filestats /path/to/any/directory --top 5
輸出示例：
?? 分析路徑：/Users/dev/myproject
擴(kuò)展名 數(shù)量 大小(MB)
──────────────────────────────────────
.py 342 1.25
.json 89 0.43
.md 31 0.18
.txt 18 0.08
.yml 12 0.02
共計 492 個文件，5 種類型
3.2 編寫測試（發(fā)布前必做）
# tests/test_core.py
import pytest
from pathlib import Path
import tempfile
from filestats.core import analyze_directory, FileStats
@pytest.fixture
def temp_dir(tmp_path: Path) -> Path:
"""創(chuàng)建測試用臨時目錄"""
(tmp_path / "a.py").write_text("print('hello')")
(tmp_path / "b.py").write_text("x = 1")
(tmp_path / "readme.md").write_text("# Test")
subdir = tmp_path / "sub"
subdir.mkdir()
(subdir / "c.py").write_text("pass")
return tmp_path
def test_analyze_directory_counts(temp_dir: Path) -> None:
stats = analyze_directory(temp_dir)
assert stats[".py"].count == 3
assert stats[".md"].count == 1
def test_analyze_directory_non_recursive(temp_dir: Path) -> None:
stats = analyze_directory(temp_dir, recursive=False)
assert stats[".py"].count == 2 # 不含子目錄
def test_invalid_path() -> None:
with pytest.raises(FileNotFoundError):
analyze_directory("/nonexistent/path")
poetry run pytest --cov=filestats
第四章：發(fā)布到 PyPI 的完整流程
4.1 準(zhǔn)備工作
第一步：注冊賬號
- PyPI 正式環(huán)境
- TestPyPI 測試環(huán)境（強(qiáng)烈建議先測試）
第二步：配置 API Token（推薦，比密碼更安全）
在 PyPI 賬戶設(shè)置中創(chuàng)建 API Token，然后配置 Poetry：
poetry config pypi-token.pypi pypi-AgEIcHlwaS5vcmcXXXXXXXXX poetry config pypi-token.testpypi pypi-AgEIcHlwaS5vcmcYYYYYYYYY
4.2 構(gòu)建前的 Checklist
發(fā)布前檢查清單
- 版本號是否已更新？（遵循 SemVer: 主.次.補(bǔ)?。?/li>
- CHANGELOG 或 README 是否已更新？
- 測試全部通過？（pytest）
- 代碼格式化？（black, ruff）
- 類型檢查通過？（mypy）
- 包名在 PyPI 上是否唯一？
版本號規(guī)范（SemVer）：
1.0.0
│ │ └── 補(bǔ)丁版本：bug 修復(fù)，向后兼容
│ └──── 次版本：新功能，向后兼容
└────── 主版本：破壞性變更
# Poetry 提供便捷的版本管理命令 poetry version patch # 1.0.0 → 1.0.1 poetry version minor # 1.0.0 → 1.1.0 poetry version major # 1.0.0 → 2.0.0
4.3 發(fā)布流程
# 步驟一：構(gòu)建發(fā)行包 poetry build # 驗(yàn)證構(gòu)建結(jié)果 ls dist/ # filestats-0.1.0.tar.gz # filestats-0.1.0-py3-none-any.whl # 步驟二：先發(fā)布到 TestPyPI 驗(yàn)證 poetry publish --repository testpypi # 步驟三：在新環(huán)境中測試安裝 pip install --index-url https://test.pypi.org/simple/ filestats filestats --help # 驗(yàn)證功能正常 # 步驟四：確認(rèn)無誤后發(fā)布正式版 poetry publish
自動化發(fā)布——GitHub Actions：
# .github/workflows/publish.yml
name: Publish to PyPI
on:
push:
tags:
- "v*" # 推送 tag 時觸發(fā)
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: "3.11"
- name: Install Poetry
run: pip install poetry
- name: Install dependencies
run: poetry install
- name: Run tests
run: poetry run pytest
- name: Build and publish
env:
POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}
run: |
poetry build
poetry publish
發(fā)布一個新版本只需要：
poetry version patch git add pyproject.toml git commit -m "chore: bump version to $(poetry version -s)" git tag v$(poetry version -s) git push && git push --tags # GitHub Actions 自動完成后續(xù)發(fā)布
第五章：最佳實(shí)踐與常見陷阱
5.1 README 是你包的門面
一個好的 README 應(yīng)該包含：
# filestats
[](https://pypi.org/project/filestats/)
[](https://www.python.org/)
> 快速統(tǒng)計目錄中各類型文件的工具
## 安裝
\```bash
pip install filestats
\```
## 快速開始
\```bash
# 統(tǒng)計當(dāng)前目錄
filestats .
# 不遞歸，只顯示前 5 種類型
filestats /path/to/dir --no-recursive --top 5
\```
## 作為庫使用
\```python
from filestats import analyze_directory
stats = analyze_directory("/path/to/dir")
\```
5.2 常見陷阱與解決方案
陷阱一：包名沖突
在 PyPI 搜索確認(rèn)名稱唯一性。包名用連字符（my-lib），但 Python 導(dǎo)入用下劃線（import my_lib），Poetry 會自動處理這個映射。
陷阱二：忘記包含必要文件
# pyproject.toml 中明確包含 [tool.setuptools.package-data] mylib = ["*.json", "*.yaml", "data/*"]
使用 Poetry 時：
[tool.poetry] include = ["filestats/data/*.json"] exclude = ["filestats/tests/*"]
陷阱三：依賴版本過于寬松或過于嚴(yán)格
# ? 過于寬松——可能引入不兼容版本 requests = "*" # ? 過于嚴(yán)格——妨礙用戶使用其他兼容版本 requests = "2.28.1" # ? 推薦：允許兼容的次版本更新 requests = "^2.28.0"
第六章：前沿展望
6.1 uv——下一代包管理器
Astral 團(tuán)隊（ruff 的作者）推出的 uv 正在快速崛起。用 Rust 編寫，速度比 pip 快 10-100 倍：
# 安裝 uv curl -LsSf https://astral.sh/uv/install.sh | sh # 極速安裝依賴 uv pip install requests # 比 pip 快 10 倍以上 # 未來：uv 可能統(tǒng)一包管理與項(xiàng)目管理 uv init myproject uv add requests uv run python main.py
6.2 可信發(fā)布（Trusted Publishing）
PyPI 正在推廣基于 OIDC 的可信發(fā)布，無需存儲 Token：
# 在 PyPI 項(xiàng)目設(shè)置中配置 GitHub Actions 可信發(fā)布后 - name: Publish to PyPI uses: pypa/gh-action-pypi-publish@release/v1 # 不需要任何密鑰！OIDC 自動認(rèn)證
總結(jié)
Python 打包生態(tài)從混亂走向統(tǒng)一，pyproject.toml 是這場變革的核心。三大工具的選擇邏輯清晰：
- Poetry：日常項(xiàng)目的不二之選，一體化體驗(yàn)最佳
- setuptools：復(fù)雜需求與 C 擴(kuò)展的堅實(shí)后盾
- Flit：極簡小包的輕盈利器
最重要的一步，永遠(yuǎn)是邁出第一步。選一個你感興趣的工具，把你手邊的項(xiàng)目打個包，發(fā)布到 TestPyPI 試試——這個過程遠(yuǎn)比想象中簡單，而那種"我的代碼可以被全世界 pip install"的成就感，真的會上癮。
以上就是Python項(xiàng)目打包與發(fā)布的三大工具(setuptools、Poetry、Flit)使用完全指南的詳細(xì)內(nèi)容，更多關(guān)于Python項(xiàng)目打包與發(fā)布的資料請關(guān)注腳本之家其它相關(guān)文章！
相關(guān)文章
在vscode中啟動conda虛擬環(huán)境的思路詳解
這篇文章主要介紹了在vscode中啟動conda虛擬環(huán)境的思路詳解,本文給大家介紹的非常詳細(xì)，對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值，需要的朋友可以參考下2020-12-12
Pydantic是一個Python庫,用于數(shù)據(jù)驗(yàn)證和解析,它基于TypeHints,提供數(shù)據(jù)驗(yàn)證和解析功能,基本用法包括定義模型、實(shí)例化與驗(yàn)證、字段約束和嵌套使用,常見應(yīng)用場景包括Web API、配置管理等,這篇文章介紹Python的Pydantic概念及基本用法,感興趣的朋友跟隨小編一起看看吧2026-01-01
這篇文章主要為大家詳細(xì)介紹了Python+OpenCV采集本地攝像頭的視頻，具有一定的參考價值，感興趣的小伙伴們可以參考一下2019-04-04
Python標(biāo)準(zhǔn)庫之日期、時間和日歷模塊
這篇文章介紹了Python標(biāo)準(zhǔn)庫之日期、時間和日歷模塊，文中通過示例代碼介紹的非常詳細(xì)。對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值，需要的朋友可以參考下2022-05-05
這篇文章主要介紹了python如何調(diào)用百度識圖api，幫助大家更好的理解和使用python，感興趣的朋友可以了解下2020-09-09
基于Keras的格式化輸出Loss實(shí)現(xiàn)方式
這篇文章主要介紹了基于Keras的格式化輸出Loss實(shí)現(xiàn)方式，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2020-06-06
可視化圖表有很多種，這篇文章主要介紹了Python繪制六種可視化圖表詳解的方法，非常不錯，具有一定的參考借鑒價值,需要的朋友可以參考下2018-08-08
在本篇文章里小編給大家分享的是一篇關(guān)于python函數(shù)體的基礎(chǔ)知識點(diǎn)，需要的朋友們可以學(xué)習(xí)下。2020-06-06
Python使用PEfile模塊實(shí)現(xiàn)分析PE文件
PeFile模塊是Python中一個強(qiáng)大的便攜式第三方PE格式分析工具，用于解析和處理Windows可執(zhí)行文件，本文主要就來講講如何使用PEfile模塊實(shí)現(xiàn)分析PE文件，需要的可以參考下2023-08-08
python?PyVCF文件處理VCF文件格式實(shí)例詳解
這篇文章主要為大家介紹了python?PyVCF文件處理VCF文件格式實(shí)例詳解，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進(jìn)步，早日升職加薪2022-07-07