A beginner-friendly guide to releasing Python packages safely.
This README is the short version. The full interactive guide lives at pypiguide.site.
Publishing a Python package looks simple until you hit the real release details:
package names, pyproject.toml, TestPyPI, tokens, clean install tests, PyPI
versions, and future updates.
PyPI Guide gives beginners a calm path from idea to public package without guessing the order.
It is written for searches like:
- how to publish a Python package
- how to upload a package to PyPI
- TestPyPI tutorial for beginners
pyproject.tomlpackage example- Python package folder structure
python -m buildandtwine upload- PyPI API token and project-scoped token setup
- how to release a new Python package version
Idea -> Name -> Package structure -> Build locally -> Upload to TestPyPI -> Clean install test -> Upload to PyPI -> Verify live package -> Secure project token -> Publish future versions
This is the quick overview. For the full beginner explanation, screenshots, warnings, Windows notes, and troubleshooting, visit pypiguide.site.
Use a clean package layout with pyproject.toml, README.md, LICENSE,
tests, and a src/ package folder.
Example:
my-package/
├── pyproject.toml
├── README.md
├── LICENSE
├── CHANGELOG.md
├── src/
│ └── mypackage/
│ ├── __init__.py
│ └── cli.py
└── tests/
└── test_cli.py
More details: Package structure guide
python -m pip install --upgrade build twine pytest
More details: Build locally and run checks
python -m pytest -q
rm -rf dist
python -m build
python -m twine check dist/*Expected output includes fresh files inside dist/, such as:
dist/
├── mypackage-0.0.1.tar.gz
└── mypackage-0.0.1-py3-none-any.whl
More details: Local build checks
python -m twine upload --repository testpypi dist/*When Twine asks for login:
username: __token__
password: pypi-your-testpypi-token-here
More details: Upload to TestPyPI
Replace your-exact-package-name with the exact name on your TestPyPI project
page.
cd /tmp python -m venv package-test source package-test/bin/activate python -m pip install --upgrade pip python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ your-exact-package-name
More details: Clean TestPyPI install
Only do this after the TestPyPI page looks correct and the clean install works.
python -m twine upload dist/*When Twine asks for login:
username: __token__
password: pypi-your-real-pypi-token-here
More details: Upload to real PyPI
cd /tmp python -m venv pypi-live-test source pypi-live-test/bin/activate python -m pip install --upgrade pip python -m pip install your-exact-package-name
If your package installs a CLI command, test that command too. If it is a library-only package, test a Python import.
More details: Verify the live PyPI release
After the first real PyPI upload succeeds, replace broad upload tokens with a project-scoped token for safer future releases.
More details: Token security step
- choosing a clear package name
- checking PyPI, TestPyPI, GitHub, and brand risk
- creating a clean
src/package layout - writing
pyproject.toml - preparing README, license, and changelog files
- creating GitHub, TestPyPI, and PyPI accounts
- enabling two-factor authentication
- creating the first all-project upload token
- building and checking package metadata
- uploading to TestPyPI first
- testing install in a clean temporary folder
- uploading to real PyPI
- verifying the live package URL
- replacing broad tokens with project-scoped tokens
- publishing future versions safely
Contributions are welcome.
Helpful improvements include clearer beginner wording, better error examples, screenshots, Windows notes, accessibility improvements, and translations.
If PyPI Guide helps you publish a package, please consider starring the repository so more beginners can find it.
Created by Ripon Chandra Malo.
Repository: github.com/riponcm/pypiguide
PyPI Guide is an independent beginner guide. It is not affiliated with PyPI, the Python Software Foundation, or the Python Packaging Authority.
MIT