Python脚本打包教程：setuptools使用指南

本文手把手教你用setuptools将Python脚本打包成专业、可分发的CLI工具：从规范的项目结构（src布局+pyproject.toml配置）起步，重点解析entry-points如何让脚本一键变成终端命令，强调本地构建、虚拟环境验证的关键避坑步骤，并清晰指引安全上传PyPI的全流程——不堆砌配置，只聚焦“发布什么”和“别人怎么用”，让打包真正变得简单、可靠、可复现。

用 setuptools 打包 Python 脚本，核心是写好 setup.py（或现代推荐的 pyproject.toml），再通过命令生成可分发的包。关键不在于堆砌配置，而在于明确“想发布什么”和“别人怎么用它”。

准备一个清晰的项目结构

别直接在脚本所在目录开干。先组织成标准小项目：

• 根目录放 pyproject.toml（或 setup.py）
• 新建 src/ 文件夹，把主模块（比如 mytool.py）放进去
• 加个 README.md 和简短的 __init__.py（如果用 src 结构，src 下不需要 __init__.py）

这样能避免本地开发路径污染安装环境，也方便测试和 CI。

用 pyproject.toml 替代 setup.py（推荐）

Python 官方已转向声明式配置。一个最小可用的 pyproject.toml 长这样：

[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "mytool"
version = "0.1.0"
description = "A simple CLI tool"
authors = [{name = "Your Name", email = "you@example.com"}]
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.25.0",
]

[project.entry-points."console_scripts"]
mytool = "mytool:main"

注意：entry-points 是让脚本能被终端直接调用的关键——安装后会自动生成 mytool 命令，指向 mytool.py 中的 main() 函数。

构建并本地验证包

别急着上传 PyPI。先本地打包、安装、运行：

• 运行 python -m build（需先 pip install build），生成 dist/mytool-0.1.0-py3-none-any.whl
• 新建虚拟环境：python -m venv test_env && source test_env/bin/activate（Windows 用 test_env\Scripts\activate）
• 安装： pip install ../dist/mytool-0.1.0-py3-none-any.whl
• 运行：mytool --help 看是否响应

这一步卡住，90% 是 entry-points 写错、模块路径不对，或 main() 没定义。

上传到 PyPI（可选但常见）

确认本地没问题后，上传只需两步：

• 注册账号（pypi.org 和测试站 test.pypi.org 各一个）
• 安装 twine：pip install twine
• 上传测试包：twine upload --repository testpypi dist/*
• 验证无误，再传正式版：twine upload dist/*

首次上传建议先走 test.pypi.org，用 pip install -i https://test.pypi.org/simple/ mytool 验证安装流程是否通。

不复杂但容易忽略：版本号每次改完要手动更新 project.version，entry-points 的函数必须可导入且无副作用，README 里最好写一句安装和用法示例。

以上就是《Python脚本打包教程：setuptools使用指南》的详细内容，更多关于的资料请关注golang学习网公众号！