Python使用PyInstaller/pip打包与发布的详细指南

目录

• 一、使用 PyInstaller 打包可执行程序
• 1. PyInstaller 是什么
• 2. PyInstaller 基本使用
• 3. 常用参数（必须掌握）
• 单文件打包
• 隐藏控制台窗口（GUI 程序）
• 加入图标
• 添加数据文件（图片、配置、模型）
• 4. 打包常见问题（超实用）
• （1）打包后无法运行 / 缺少模块
• （2）打包文件太大？
• （3）Mac 打包的 app 无法在另一台 Mac 运行
• 二、Python 包发布到 PyPI（pip install 可用）
• 1. 项目结构（最推荐）
• 2. 使用 build 进行构建
• 3. 发布到 TestPyPI
• 4. 正式发布到 PyPI
• 5. pyproject.toml 示例（最推荐）
• 6. PyPI 发布常见问题
• 403 权限错误
• 版本号冲突
• 依赖未安装
• 三、两者对比：应该用哪个
• 四、最佳实践总结

本篇博客从零到一带你熟悉：

• PyInstaller：把 Python 项目打包成 EXE / APP
• pip 包发布流程：把你的项目推向 PyPI
• 常见坑与最佳实践

让你写的 Python 程序能真正“走出去”，触达更多真实用户。

PyInstaller 是将 Python 程序打包成可执行文件（如 Windows 的 .exe）的最常用工具。它会把 Python 解释器 + 所有依赖打包进一个独立文件，用户无需 Python 环境即可运行。

适合场景：

• 给用户分发桌面工具
• 内部办公自动化脚本
• GUI 程序（Tkinter、PyQt、wxPython 等）
• 命令行工具

安装：

pip install pyinstaller

最简单的打包：

pyinstaller main.py

完成后，目录结构如下：

dist/
    main/
        main.exe
build/
main.spec

最终可执行文件就在 dist 目录里。

pyinstaller -F main.py

优点：只生成一个 .exe 缺点：启动稍慢

pyinstaller -F -w main.py

pyinstaller -F -i icon.ico main.py

推荐在 .spec 文件中配置：

a = Analysis(
    ...,
    datas=[('config.yml', 'config.yml'), ('assets/', 'assets/')],
)

然后：

pyinstaller main.spec

原因：PyInstaller 未能自动识别依赖 解决：

pyinstaller -F main.py --hidden-import xx_module

解决方式：

• 使用 UPX 压缩
• 删除 matplotlib/numpy 中用不到的 DLL

因为 macOS 的签名安全机制，建议：

• 在目标版本系统构建（如 macOS 14）
• 结合 codesign --deep 进行签名

让别人可以：

pip install yourpackage

这是专业 Python 开发者的重要能力之一。

myproject/
    myproject/
        __init__.py
        core.py
    tests/
    README.md
    pyproject.toml
    LICENSE

最关键：使用 pyproject.toml（现代标准）

安装：

pip install build twine

构建：

python -m build

生成：

dist/
    myproject-1.0.0.tar.gz
    myproject-1.0.0-py3-none-any.whl

避免污染正式 PyPI。

twine upload --repository testpypi dist/*

安装测试版：

pip install -i https://test.pypi.org/simple/ myproject

twine upload dist/*

全世界的人就都可以：

pip install myproject

下面是一个专业示例，可直接复用：

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

[project]
name = "myproject"
version = "1.0.0"
authors = [
    { name="Your Name", email="you@example.com" }
]
description = "A powerful and modern Python utility."
readme = "README.md"
license = { file="LICENSE" }
requires-python = ">=3.8"
dependencies = ["requests", "numpy"]

[project.urls]
Homepage = "https://github.com/you/myproject"
Documentation = "https://myproject-docs.com"

未创建 API Token 或 Token 配置错误 → 进入 pypi.org/manage/account/ 创建 Token 并更新 .pypirc

PyPI 版本号不能重复 → 每次发布前更新版本号（如：1.0.1 → 1.0.2）

确保 dependencies 正确写到 pyproject.toml

场景	PyInstaller	PyPI 包发布
给普通用户（没 Python 环境）	✔ 最佳选择	✘
给开发者	✔	✔✔（最推荐）
分发 GUI 工具	✔	无意义
库 / SDK 发布	✘	✔最佳

办公/桌面工具 → PyInstaller：稳定、方便、用户无须 Python

开发者工具 → PyPI 发布：现代 Python 项目的标准做法

推荐结合 CI 自动化发布：GitHub Actions + PyPI + build 可以做到“打 tag 自动发布”

到此这篇关于Python使用PyInstaller/pip打包与发布的详细指南的文章就介绍到这了,更多相关Python项目打包与发布内容请搜索风君子博客以前的文章或继续浏览下面的相关文章希望大家以后多多支持风君子博客！

您可能感兴趣的文章:

• 使用PyInstaller打包Python项目过程
• 使用PyInstaller打包Python脚本为可执行文件的详细指南
• python之PyInstaller(将Python脚本打包为可执行文件方式)
• 使用PyInstaller如何打包一个包含多个文件的Python项目
• PyInstaller打包Python脚本的使用示例
• 如何将python代码打包成pip包(可以pip install)
• Pyinstaller+Pipenv打包Python文件的实现示例
• Python基于pip实现离线打包过程详解