Introduction
You’ve written a useful Python module. The next step is sharing it — and PyPI (the Python Package Index) is where the world installs Python packages. Publishing takes ~15 minutes the first time, and ~2 minutes after that.
This post walks through the entire process: structure, config, build, and publish.
Step 1: Project structure
mypackage/
├── src/
│ └── mypackage/
│ ├── __init__.py
│ └── core.py
├── tests/
│ └── test_core.py
├── pyproject.toml
├── README.md
└── LICENSE
Use the src/ layout — it prevents accidental imports of your local code instead of the installed package.
Step 2: __init__.py
# src/mypackage/__init__.py
"""My awesome package."""
__version__ = "0.1.0"
from .core import greet
__all__ = ["greet", "__version__"]
Step 3: Your code
# src/mypackage/core.py
def greet(name: str) -> str:
"""Return a greeting."""
return f"Hello, {name}!"
Step 4: pyproject.toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "mypackage"
version = "0.1.0"
description = "A short description of your package"
readme = "README.md"
license = {text = "MIT"}
requires-python = ">=3.9"
authors = [{name = "Your Name", email = "[email protected]"}]
keywords = ["greeting", "example"]
classifiers = [
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
]
dependencies = []
[project.urls]
Homepage = "https://github.com/yourname/mypackage"
Repository = "https://github.com/yourname/mypackage"
Issues = "https://github.com/yourname/mypackage/issues"
[project.optional-dependencies]
dev = ["pytest", "ruff", "mypy"]
[tool.hatch.build.targets.wheel]
packages = ["src/mypackage"]
Step 5: README.md
# mypackage
A short description.
## Install
```bash
pip install mypackage
Usage
from mypackage import greet
print(greet("World")) # Hello, World!
License
MIT
## Step 6: Build
```bash
# With uv (recommended)
uv build
# Or with build
pip install build
python -m build
Creates dist/:
dist/
├── mypackage-0.1.0.tar.gz # source distribution
└── mypackage-0.1.0-py3-none-any.whl # wheel (binary)
Always publish both — the wheel for fast installs, the sdist for source.
Step 7: Test locally
pip install dist/mypackage-0.1.0-py3-none-any.whl
python -c "from mypackage import greet; print(greet('Galvan'))"
Or use twine check dist/* to validate metadata.
Step 8: Publish to PyPI
Create an account
- Go to pypi.org/account/register.
- Enable 2FA (required).
- Create an API token: Account Settings → API tokens → “Add API token” (scope: entire account or specific project).
Upload
# With uv
uv publish
# Or with twine
pip install twine
twine upload dist/*
# Username: __token__
# Password: pypi-xxxxxxxxxxxx
Your package is now live at https://pypi.org/project/mypackage/.
Test on TestPyPI first (recommended)
# Upload to TestPyPI
twine upload --repository testpypi dist/*
# Install from TestPyPI
pip install --index-url https://test.pypi.org/simple/ mypackage
TestPyPI is a separate instance for testing. Use it before publishing to real PyPI.
Step 9: Versioning and updates
Follow Semantic Versioning:
0.1.0→0.1.1(patch: bug fix)0.1.0→0.2.0(minor: new feature, backward compatible)0.1.0→1.0.0(major: breaking change)
To release a new version:
- Bump
versioninpyproject.toml. uv builduv publish
Step 10: CI/CD (automated publishing)
# .github/workflows/publish.yml
name: Publish to PyPI
on:
release:
types: [published]
jobs:
publish:
runs-on: ubuntu-latest
permissions:
id-token: write # for trusted publishing
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v4
- run: uv build
- uses: pypa/gh-action-pypi-publish@release/v1
With trusted publishing (OIDC), no API token needed — PyPI trusts your GitHub repo. Set it up in PyPI → Your project → Publishing.
Common mistakes
- Name already taken — check PyPI first. Use a unique name (e.g.,
mypackage-galvan). - Missing
__init__.py— without it, the package won’t be importable. - Wrong
packagespath —packages = ["src/mypackage"]must match your layout. - Not testing locally — always install from
dist/before publishing. - Forgetting the README — PyPI displays it on the project page. Make it good.
- Version conflicts — you can’t re-upload the same version. Bump the version.
Key Concepts
- PyPI = the Python Package Index (pip installs from here)
- Wheel = pre-built binary (fast install)
- sdist = source distribution (builds on install)
pyproject.toml= project metadata and build config- Semantic versioning = major.minor.patch
- Trusted publishing = OIDC-based auth (no tokens in CI)
What to Try Next
- Add type hints and publish a typed package (
py.typedmarker). - Add tests with pytest and run in CI.
- Document with Sphinx or MkDocs.
- Publish a CLI tool as a package with entry points.
FAQ
PyPI vs TestPyPI — which to use?
TestPyPI for testing the upload/install flow. Real PyPI for production. Always test on TestPyPI first for new packages.
How do I make my package discoverable?
Good README, relevant keywords in pyproject.toml, classifiers, and a clear description. PyPI search ranks by name and description. Also add a GitHub repo link.
Can I unpublish a package?
You can delete a release within 72 hours of publishing. After that, you can only yank (mark as broken) — the files stay. Be careful with what you publish. Never publish secrets.