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

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

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

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

一、使用 PyInstaller 打包可执行程序

1. PyInstaller 是什么

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

适合场景：

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

2. PyInstaller 基本使用

安装：

pip install pyinstaller

最简单的打包：

pyinstaller main.py

完成后，目录结构如下：

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

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

3. 常用参数（必须掌握）

单文件打包

pyinstaller -F main.py

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

隐藏控制台窗口（GUI 程序）

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

4. 打包常见问题（超实用）

（1）打包后无法运行 / 缺少模块

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

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

（2）打包文件太大？

解决方式：

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

（3）Mac 打包的 app 无法在另一台 Mac 运行

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

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

二、Python 包发布到 PyPI（pip install 可用）

让别人可以：

pip install yourpackage

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

1. 项目结构（最推荐）

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

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

2. 使用 build 进行构建

安装：

pip install build twine

构建：

python -m build

生成：

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

3. 发布到 TestPyPI

避免污染正式 PyPI。

twine upload --repository testpypi dist/*

安装测试版：

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

4. 正式发布到 PyPI

twine upload dist/*

全世界的人就都可以：

pip install myproject

5. pyproject.toml 示例（最推荐）

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

[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"

6. PyPI 发布常见问题

403 权限错误

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

版本号冲突

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

依赖未安装

确保 dependencies 正确写到 pyproject.toml

三、两者对比：应该用哪个

四、最佳实践总结

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

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

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

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