当前位置:

首页 > 编程开发 > Python如何将自建项目打包上传至PyPI_使用setuptools与twine

Python如何将自建项目打包上传至PyPI_使用setuptools与twine

WindowTop
WindowTop

WindowTop是一款窗口自定义设置工具,实现置顶、透明度调整、界面模糊、暗色模式及缩小窗口等功能。界面整理和高频系统操作被放到一起考虑,桌面或窗口内容一多时,管理起来会更省心。

立即下载
¥109
Windows 2026-09-24
正版软件 Windows 窗口管理工具

Python打包上传至PyPI需用pyproject.toml,填写name、version、description、readme必填字段。上传须用APItoken,禁用密码。上传前执行三步检查:python-mbuild生成包,twinecheck验证描述,再在虚拟环境安装测试。确保包结构正确,避免版本号不一致。

本文目录

    能传上去,但大概率第一次会失败——不是代码问题,而是 setup.py 或 pyproject.toml 里少写了关键元数据,或者认证方式没走对 twine 流程。

    setup.py 和 pyproject.toml 到底该用哪个?

    Python 官方现在的态度很明确:优先用 pyproject.toml,setup.py 属于“能用但别再新写了”的状态。新项目直接上 pyproject.toml,省得以后还得迁移。

    几个关键点:

    • 如果你的 setuptools 版本不低于 61.0,pyproject.toml 可以完全取代 setup.py,两者没必要同时存在
    • 就算 setup.py 还在目录里,默认也会被忽略,除非你显式在 [build-system] 里指定它
    • 最常见的翻车案例:只改了 setup.py 里的版本号,却忘了同步 pyproject.toml 中的 version 字段,结果本地测试好好的,上传后打的包版本完全不对

    pyproject.toml 必须填哪些字段才能过 PyPI 校验?

    PyPI 在上传时对元数据的校验相当严格,缺一个字段就给你打回来。description 和 readme 是最容易被漏掉的,哪怕内容只写一行也能过关,但绝不能空着。

    具体看看哪些是必填项:

    • name:必须全小写,只能包含字母、数字和短横线。比如 my-awesome-lib 没问题,但 MyAwesomeLib 就会被拒
    • version:推荐用 dynamic 方式从 __version__ 读取,省得手动维护两份
    • description:不能为空,哪怕写一句 "A small utility" 也行
    • readme:文件路径必须正确,比如 "README.md"。如果不配这个字段,twine check 会直接报错 Invalid value for 'long_description': No content type specified.
    • requires-python:例如 >=3.8,不写的话包能上传成功,但别人安装时会提示 Package requires Python >=3.x but running on 3.y

    twine upload 总是 403 或 “invalid or non-existent authentication information”

    这不是密码输错了,而是你没用 PyPI 的 API token,还试图用账号密码登录——从 2023 年开始,PyPI 已经禁止密码直接上传了。

    正确的做法是:

    • 去 PyPI 官网创建一个 Scoped token,限制到具体项目名会更安全
    • 上传命令必须带上 --repository 参数:测试用 twine upload --repository testpypi,正式用 twine upload --repository pypi
    • 凭证可以放在 ~/.pypirc 文件里,或者用环境变量配置:TWINE_USERNAME=__token__ 和 TWINE_PASSWORD=你的token
    • 有个常见坑:运行 twine upload dist/* 时,如果 dist/ 目录里混着旧包(比如不同版本或同时有 .tar.gz 和 .whl),很容易因为重复上传而失败。建议每次上传前先执行 rm -rf dist/ 清理一下

    上传前必须跑的三步本地检查

    跳过这三步,90% 的上传失败都发生在这里,而且错误信息藏得特别深。

    第一步:python -m build,生成 dist/ 目录下的 .whl 和 .tar.gz 文件。如果这一步失败,说明 pyproject.toml 的语法或者依赖声明有问题。

    第二步:twine check dist/*,验证包描述能否正确解析、README 格式是否合法。如果报 InvalidDistribution,多半是 readme 路径写错了,或者没指定 content-type。

    第三步:pip install --find-links dist/ --no-index your-package-name,在一个干净的虚拟环境中安装一遍。这一步非常关键——很多包上传后能装成功,但 import 的时候报 ModuleNotFoundError,原因就是 packages 字段没有自动发现子模块。

    最麻烦的其实是包结构本身的问题。比如你的模块放在 src/mylib/ 目录下,但 pyproject.toml 里没配 packages = [{include = "mylib", from = "src"}],那么生成的 wheel 文件里就根本没有代码。这种问题 twine check 是检查不出来的,只有最后那步本地安装验证才能抓到。

    本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系bd@zhengruan.com
    作者最新文章
    编程开发 Python win
    相关文章 更多
    python删除一个列表里的重复元素的方法与代码示例
    python删除一个列表里的重复元素的方法与代码示例

    学习如何使用Python高效删除列表中的重复元素。本文提供5种常见方法的代码示例,涵盖保持顺序与不保持顺序的场景,适合初学者和进阶开发者参考。

    Python写接口的步骤及完整代码示例
    Python写接口的步骤及完整代码示例

    详细讲解使用Python编写Web接口的核心步骤与完整代码示例,涵盖环境准备、路由定义、数据校验、服务启动及调试测试方法。

    codex怎么读取word文档及docx文件操作教程
    codex怎么读取word文档及docx文件操作教程

    介绍如何利用编程工具读取和解析Word文档(docx格式),涵盖基础文本提取代码示例、结构化数据处理逻辑,以及处理复杂排版时的技术局限与替代方案。

    怎么在Python中调用C语言代码提升性能
    怎么在Python中调用C语言代码提升性能

    详细讲解在Python中调用C语言代码提升性能的完整实践指南,包含原理分析、编译步骤、ctypes与CFFI具体实现、性能对比及常见陷阱。

    Python与C语言的性能差异及底层原理
    Python与C语言的性能差异及底层原理

    深入解析Python与C语言在执行效率上的数量级差异,从编译机制、变量内存布局、动态类型推断到GIL锁,系统阐明底层核心原理。

    Python和C语言哪个更适合编程入门
    Python和C语言哪个更适合编程入门

    客观对比Python与C语言在心智负担、底层机制与学习反馈上的核心差异,提供清晰有据的选择标准与切实的入门学习路径。

    selenium上传文件教程本地文件路径设置方法
    selenium上传文件教程本地文件路径设置方法

    深入解析Selenium处理文件上传的技术细节,涵盖标准HTML控件的路径直接注入法与非标准控件的系统级模拟方案,提供Windows与Linux环境下的路径设置最佳实践及常见异常排查。

    大数据开发语言选型:Java对比Scala与Python的优缺点及适用场景
    大数据开发语言选型:Java对比Scala与Python的优缺点及适用场景

    针对大数据工程场景,系统对比Java、Scala与Python在执行性能、生态结合、开发效率和维护成本上的核心差异,给出清晰的架构选型依据与落地方案。

    langgraph python guide中文入门教程详解
    langgraph python guide中文入门教程详解

    本篇LangGraph Python中文入门教程详解,系统梳理StateGraph状态机定义、节点编写、边与条件路由、检查点持久化(MemorySaver)等核心机制,提供从环境安装到完整循环智能体构建的代码示例与实操指导。

    Windows 安装 Python:从官方入口到虚拟环境的可复现实践
    Windows 安装 Python:从官方入口到虚拟环境的可复现实践

    面向后端开发者,基于 Python 官方文档说明如何在 Windows 上安装 Python、创建 venv 虚拟环境及使用 pip 管理依赖。包含可复制命令、验证方法及工具选择边界,避免常见配置误区。

    查看更多
    精品专题 更多
    装机必备
    装机必备

    正软商城装机必备专区,精选办公、浏览器、安全防护、影音播放、压缩解压、设计创作和系统工具等电脑常用正版软件,帮助用户快速完成新电脑软件配置。

    Windows
    Windows

    正软商城Windows软件专区,汇集适用于Windows电脑的办公、设计、安全防护、影音播放、开发工具和系统优化软件,提供软件介绍、系统要求、正版授权及购买下载服务。

    PDF教程
    PDF教程

    正软商城PDF教程频道提供PDF编辑、转换、合并、拆分、压缩及格式处理方法,同时介绍常用PDF软件和工具的使用技巧。

    Mac软件 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    Aperty macOS版
    Aperty macOS版
    macOS

    Aperty 是 Skylum 推出的 AI 人像修图软件,支持自然肤质修饰、瑕疵处理、面部与身体调整、预设及批量同步。

    WINDOWS 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    PixTV 网页版
    PixTV 网页版
    Windows

    PixTV 是一款在浏览器中使用的 AI 视觉内容创作平台,提供图片、视频、音频、文字生成、AI 分镜、局部重绘、提示词反推和无限画布等工具,适合短剧、漫剧、广告及社交媒体内容制作。

    即将离开本站
    您即将前往第三方网站,请确认是否继续?