You have a useful script, a small library, or a new idea. You want it on GitHub in a shape others can install, test, and later download from PyPI. Packaging has many tools (frontends, backends, environment managers, linters), and it is easy to confuse "set up every advanced CI control" with "make a package that installs correctly."
Most new libraries only need a short checklist done well: name, layout, build backend, metadata, a little quality tooling, then build and check the artifacts. When a step needs a full decision tree, this post links to a companion post.
The running example is a tiny pure-Python library, checklist-demo; the same steps apply to a CLI. The goal is a repository that installs and passes checks before the first outside pull request, not a perfect OpenSSF score on the first afternoon.
1. Naming
You need two names. Keep them close.
Distribution name: what people type in pip install or uv add. Put it in [project].name. It must be free on PyPI. Check with https://pypi.org/pypi/<name>/json. HTTP 404 means the name is free. Names are normalized: case does not matter, and -, _, and . count as the same. So My_Pkg, my-pkg, and my.pkg are one name. One check covers all spellings. Avoid names one letter away from a popular project; they look like typosquats.
Import name: what people type after import. It must be a valid Python name, so use underscores, not hyphens. Example: install checklist-demo, import checklist_demo. The import name is the folder under src/.
For a new package, use a matching pair such as my-pkg / my_pkg. Check PyPI before you create the repo. Renaming later is painful.
2. Folder layout (src/)
Put the importable code under src/, not next to tests/ at the repo root:
checklist-demo/
├── LICENSE
├── README.md
├── pyproject.toml
├── src/
│ └── checklist_demo/
│ ├── __init__.py
│ └── py.typed
└── tests/
└── test_greet.py
Why src/: A flat layout lets pytest import from the checkout. That is easy, but tests never see the package as users install it. Bugs such as missing files or an empty wheel can slip through. With src/, tests import only after an install (editable is fine). Hynek Schlawack’s Testing & Packaging explains this well. Hatchling finds this layout on its own.
Tests: Keep them in top-level tests/ unless you mean to ship them. Put private helpers in modules like _internal.py. Re-export the public API from __init__.py.
Type hints: If you ship types, add an empty py.typed next to __init__.py (PEP 561) and the Typing :: Typed classifier. Type checkers look for the marker in the installed package, so it must be in the wheel. Build once and check. Do not add the marker without real annotations.
3. Choosing how the package is built
A build backend turns the source tree into an sdist and a wheel. You declare it in [build-system]. Frontends such as uv build or python -m build call the backend through PEP 517.
For a new project, this table is enough:
| Project | Backend |
|---|---|
| Pure Python (default) | hatchling |
| Rust extensions | maturin |
| Meson / scientific C, C++, Fortran, Cython | meson-python |
| CMake / many nanobind or CUDA builds | scikit-build-core |
If you compile native code, pick the backend that matches your toolchain. The pure-Python choice among hatchling, uv-build, and flit-core, and when to stay on setuptools, is covered in another companion post Build backends for pure Python packages. This checklist uses hatchling: it is the backend in PyPA’s worked pyproject.toml example, it supports static and dynamic metadata, and it leaves room to grow. If your project already uses another backend that works, keep it.
Version numbers. On GitHub, deriving the version from git tags keeps hand-edited release strings out of pyproject.toml. With hatchling, use hatch-vcs:
[build-system]
requires = ["hatchling >= 1.27", "hatch-vcs"]
build-backend = "hatchling.build"
[project]
name = "checklist-demo"
dynamic = ["version"]
# ...
[tool.hatch.version]
source = "vcs"
Tag v0.1.0, and the built metadata reports 0.1.0. Between tags you get a development version that shows how far you are past the last release. That helps in bug reports, and PyPI rejects it on upload because it includes a local version segment. Before the first tag, a static version = "0.1.0" (with no dynamic entry) is fine for local builds; the companion post uses that style too. Switch to hatch-vcs when tags become your release signal. CI jobs that build with hatch-vcs need the full tag history (fetch-depth: 0 on checkout), or the version falls back to a useless default.
4. Project metadata (pyproject.toml)
The [project] table says what the package is and what it needs. Writing your pyproject.toml covers every field. A good starting point for the example:
[build-system]
requires = ["hatchling >= 1.27"]
build-backend = "hatchling.build"
[project]
name = "checklist-demo"
version = "0.1.0"
description = "Tiny pure-Python package for a packaging checklist walkthrough"
readme = "README.md"
requires-python = ">=3.10"
license = "MIT"
license-files = ["LICENSE"]
authors = [{ name = "Example Author", email = "author@example.com" }]
keywords = ["example", "packaging"]
classifiers = [
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3 :: Only",
"Typing :: Typed",
]
dependencies = []
[project.urls]
Homepage = "https://github.com/example/checklist-demo"
Repository = "https://github.com/example/checklist-demo"
Issues = "https://github.com/example/checklist-demo/issues"
[project.scripts]
checklist-demo = "checklist_demo:main"
Habits that pay off early:
description: One line in PyPI search results.readme: The long page. Point it atREADME.md. The backend reads the file from the extension. Nosetup.pyneeded.license: Use an SPDX id such asMITorApache-2.0. Put the text inLICENSE. List it inlicense-files. Usehatchling >= 1.27(or setuptools 77+) for these PEP 639 fields. Use twine 6.1+ to upload Metadata-Version 2.4.requires-python: A floor (>=3.10), not a ceiling. Pick a version that still gets security fixes.- Dependencies: Runtime needs go in
[project.dependencies]. Use extras only for optional features. Set lower bounds (httpx>=0.27). Skip guessy upper caps in libraries; every user inherits them. See Henry Schreiner’s bound constraints post. classifiers: Help search. They do not limit installs. Add oneProgramming Language :: Python :: 3.Xper version you test. AddTyping :: Typedif you shippy.typed. Full list: pypi.org/classifiers.[project.urls]: Use well-known labels. Prefer Homepage, Repository, and Issues.[project.scripts]: Optional CLI entry point. Form:module:functionfrom the package undersrc/.
Dev-only tools such as pytest and ruff belong in PEP 735 [dependency-groups], not in runtime dependencies or extras. For day one, a README with the pip install checklist-demo line and a three-line quickstart is enough.
Also add a LICENSE file that matches the SPDX ID in license, a .gitignore (GitHub’s Python.gitignore is a good base), and a short SECURITY.md explaining how to report vulnerabilities. Poetry migrations, generated READMEs, and guards against uploading private packages are separate jobs.
5. Quality tools (related, not pure packaging)
Users care that the import works. Before you share the repo, set a small bar:
- ruff: lint (and format, if you want one tool)
- pytest: tests under
tests/ - type checker: only if you ship
py.typed
Put them in a dev group, not in runtime deps:
[dependency-groups]
dev = ["pytest>=8", "ruff>=0.8"]
[tool.pytest.ini_options]
testpaths = ["tests"]
A first test after install (editable is fine):
from checklist_demo import greet
def test_greet() -> None:
assert greet("world") == "hello, world"
Install and run: uv sync --group dev, then ruff check and pytest. Skip tox, nox, and multi-version CI here; that belongs in a release guide.
6. Building and checking the package
With the backend and metadata in place, build the files you would upload. uv build (or python -m build) asks the declared backend for an sdist and a wheel:
$ uv build
Building source distribution...
Building wheel from source distribution...
Successfully built dist/checklist_demo-0.1.0.tar.gz
Successfully built dist/checklist_demo-0.1.0-py3-none-any.whl
The wheel name ends in py3-none-any: any Python 3, no native ABI, any platform. That is what a pure-Python package should produce.
Check the metadata and README rendering before anything reaches PyPI. Twine‘s check command reads the distributions and reports problems, such as a missing long description, without uploading:
$ uvx twine check dist/*
Checking dist/checklist_demo-0.1.0-py3-none-any.whl: PASSED
Checking dist/checklist_demo-0.1.0.tar.gz: PASSED
Then install the wheel into a clean virtual environment, not your editable development checkout, and import the package or run the console script. This confirms the src/ layout was packaged correctly, including py.typed if you added it:
$ uv venv /tmp/checklist-demo-venv
$ uv pip install --python /tmp/checklist-demo-venv dist/checklist_demo-0.1.0-py3-none-any.whl
$ /tmp/checklist-demo-venv/bin/checklist-demo
hello, world
twine check catches metadata mistakes; it does not replace tests. When you publish, prefer Trusted Publishing from GitHub Actions over a long-lived PyPI API token. Setting up that workflow and the rest of a hardened release pipeline is the next layer after this checklist.
Further reading
- Build backends for pure Python packages: companion on pure-Python backends
- How Python Packages Build Themselves: PEP 517 hooks and build isolation
- Thanks to Christian Heimes’s
bootstrap-python-projectskill for shaping this list.
Leave a Reply