Tech With Galvan
Back to Articles
DevelopmentDec 20, 2026 • 5 min read

Publish a Python Package to PyPI (Step-by-Step)

Build and publish a Python package to PyPI — project structure, pyproject.toml, building, and publishing with uv or twine. Your first open-source release.

Galvan
Galvan

Founder & Creator

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

  1. Go to pypi.org/account/register.
  2. Enable 2FA (required).
  3. 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/.

# 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:

  1. Bump version in pyproject.toml.
  2. uv build
  3. uv 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 packages path — 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.typed marker).
  • 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.