How to Publish a Python Project on GitHub and PyPI: setup.py, Packaging, pydoc, Versioning, and License Selection

This article introduces what individuals or enterprises need to know and pay attention to when publishing a Python project on GitHub.

How to configure setup.py

How to publish to PyPI

Generating pydoc documentation

Choosing a version number

Selecting a license

Configure setup.py

Packaging and publishing are performed by preparing a setup.py file. Assuming the project directory structure is as follows:

demo
├── LICENSE
├── README.md
├── MANIFEST.in  # customizes the content of dist/*.tar.gz
├── demo
│   └── __init__.py
├── setup.py
├── tests
│   └── __init__.py
│   └── __pycache__/
└── docs

Running the command python setup.py sdist bdist_wheel will generate two files in the dist directory: demo-1.0.0-py3-none-any.whl and demo-1.0.0.tar.gz .

The .whl file can be installed with pip install dist/demo-1.0.0-py3-none-any.whl which places the package under the site‑packages directory.

The .tar.gz file is a source archive; the MANIFEST.in file controls which files are included.

Example MANIFEST.in to customize the content of dist/*.tar.gz :

include LICENSE
include README.md
include MANIFEST.in
graft demo
graft tests
graft docs
global-exclude __pycache__
global-exclude *.log
global-exclude *.pyc

When the command python setup.py sdist bdist_wheel is executed, the resulting demo-1.0.0.tar.gz will contain the LICENSE, README.md, MANIFEST.in files, the demo , tests , and docs directories, while excluding __pycache__ , *.log , and *.pyc files.

For more syntax details, see the official documentation at https://packaging.python.org/guides/using-manifest-in/.

1. Official examples and documentation: https://packaging.python.org/tutorials/packaging-projects/ 2. Python sample project: https://github.com/pypa/sampleproject

Reviewing these links will fully satisfy the typical requirements for publishing a project.

Publish to PyPI

Python developers can install external libraries using pip install <package> . To share an open‑source project, publish it to the Python Package Index (PyPI) for easy installation by users.

What is PyPI?

PyPI (The Python Package Index) is a repository for finding, installing, and publishing Python packages.

PyPI has two environments:

Test environment TestPyPI: https://test.pypi.org/

Production environment PyPI: https://pypi.org/

Preparation

If you want to familiarize yourself with the publishing tools and workflow, use the TestPyPI environment.

If you are already comfortable with the tools, publish directly to the production PyPI.

Both TestPyPI and PyPI require separate registrations; the same account cannot be registered on both simultaneously.

Assuming your project is ready, run the following commands to publish it:

rm dist/*
# generate .tar.gz source archive and .whl wheel file
python setup.py sdist bdist_wheel
# upload to TestPyPI
twine upload --repository testpypi dist/*
# upload to PyPI
twine upload dist/*

About pydoc

Python includes a built‑in documentation tool called pydoc . Running python -m pydoc shows its options and capabilities.

cd docs
python -m pydoc -w ..   # generate all documentation

Running python -m pydoc -b starts a local web server to browse documentation for all libraries under the site‑packages directory.

These local web docs can be made publicly accessible via GitHub Pages. Enable GitHub Pages in the repository settings, select a branch and path, and you will obtain URLs such as:

https://xxxxx.github.io/demo/ – project homepage showing README.md

https://xxxxx.github.io/demo/docs/demo.html – pydoc documentation page

Version Number Selection

For a formal release, choose an appropriate version number:

Start with 0.0.1 for simple, incomplete features.

Start with 1.0.0 for mature, feature‑complete releases.

A typical release cycle includes Alpha, Beta, Release Candidate, and Final releases. Example version schemes:

X.YaN   # Alpha release
X.YbN   # Beta release
X.YrcN  # Release Candidate
X.Y     # Final release

Resulting version numbers look like:

Alpha: 1.1.0a1 , 1.1.0aN

Beta: 1.1.0b1 , 1.1.0bN

Release Candidate: 1.1.0rc1 , 1.1.0rcN

Final: 1.1.0 , 1.1.1 , 1.1.N

Python's versioning and dependency specification: https://www.python.org/dev/peps/pep-0440

License Selection

For enterprise projects, the legal team typically provides the license file, and the publisher formats it (e.g., wrapping lines at 70‑80 characters).

For personal projects or learning purposes, common open‑source licenses include (ordered by number of conditions):

GNU AGPLv3

GNU GPLv3

GNU LGPLv3

Mozilla Public License 2.0

Apache License 2.0

MIT License

Boost Software License 1.0

The Unlicense

For more guidance, see the article "How to Choose an Open‑Source License for a GitHub Repository" and resources such as https://choosealicense.com/licenses, https://github.com/github/choosealicense.com, and https://choosealicense.com/appendix.