上传Python项目到PyPI

前言

本教程介绍如何将 Python 项目上传到 PyPI，使用 twine 进行上传，并涵盖以下三种情况：

  1. 一般方式（基于 setup.py）

  2. 使用 Poetry

  3. 不使用 setup.py（基于 pyproject.toml）

你也可以直接查看官方文档

先决条件

在开始之前，你需要：

  • 在 GitHub 上创建一个新的仓库，并推送你的项目代码。
  • 在 PyPI 上创建一个账号，并创建相应的项目（首次上传时自动创建）

1. 创建 API Token

1.1 注册 PyPI 账号

访问 PyPI 官网 并注册一个账号。

1.2 创建 API Token

PyPI 注册可能会要求开启2FA（两步认证），可以下载微软的验证App扫码通过或者直接安装浏览器插件保存密钥。

  1. 登录 PyPI 后，点击右上角的用户名。
  2. 选择 Account settings。
  3. 在 API tokens 部分，点击 Add API token(或者直接跳转)。
  4. 选择 Scope（可以选择适用于所有项目或仅适用于某个项目），不想麻烦直接选择 All projects即可。
  5. 生成 Token 并妥善保存。

1.3 配置 Token

Windows

在用户主目录 (C:\Users\YourUsername\) 下创建 .pypirc 文件（如果不存在）添加以下内容：

1
2
3
4
5
6
7
[distutils]
index-servers =
    pypi

[pypi]
  username = __token__
  password = your_pypi_api_token

Linux/macOS

1
sudo vim ~/.pypirc

在 ~/.pypirc 文件中添加以下内容：

1
2
3
4
5
6
7
[distutils]
index-servers =
    pypi

[pypi]
  username = __token__
  password = your_pypi_api_token

2. 上传项目

1. 一般方式（基于 setup.py）

1.1 安装必要工具

1
pip install setuptools wheel twine

1.2 创建 setup.py

在项目根目录创建 setup.py 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
from setuptools import setup, find_packages

setup(
    name='your_package_name',  # 包名
    version='0.1.0',
    packages=find_packages(),
    install_requires=[
        'requests',  # 依赖包列表
    ],
    author='Your Name',  # 作者名
    author_email='your_email@example.com',  # 作者邮箱
    description='A brief description of your package',  # 项目简介
    url='https://github.com/your_username/your_repo',  # 项目地址
    classifiers=[
        'Programming Language :: Python :: 3',  # Python 版本
        'License :: OSI Approved :: MIT License',  # 许可证
        'Operating System :: OS Independent',  # 操作系统
    ],
    python_requires='>=3.9', # Python 版本要求
)

1.3 生成分发包

1
python setup.py sdist bdist_wheel

生成的 .tar.gz 和 .whl 文件会存放在 dist/ 目录下。

1.4 上传到 PyPI

1
twine upload dist/*

2. 使用 Poetry

2.1 安装 Poetry

1
pip install poetry

2.2 初始化项目

1
poetry init

按照提示填写项目信息。

2.3 配置 PyPI 认证

1
poetry config pypi-token.pypi your_pypi_api_token

2.4 构建并上传

1
2
poetry build
poetry publish

3. 不使用 setup.py（基于 pyproject.toml）

3.1 安装 build

1
pip install build

3.2 创建 pyproject.toml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "your_package_name"
version = "0.1.0"
description = "A brief description of your package"
authors = [
    { name="Your Name", email="your_email@example.com" }
]
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "requests"
]
license = { text = "MIT" }

[project.urls]
"Homepage" = "https://github.com/your_username/your_repo"

3.3 生成分发包

1
python -m build

3.4 上传到 PyPI

如果想先测试上传，可以使用 TestPyPI：

1
twine upload --repository testpypi dist/*

然后在 https://test.pypi.org/ 上查看效果。

确认无误后，再上传到正式 PyPI：

1
twine upload dist/*

5. 总结

  • 一般方式 使用 setup.py 和 twine 进行构建和上传。
  • Poetry 提供更现代的依赖管理和自动上传方式。
  • 基于 pyproject.toml 可替代 setup.py，配合 build 和 twine 上传。

选择适合自己的方式，即可轻松发布 Python 包到 PyPI！