A Checklist for a New Python Package on GitHub

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 at README.md. The backend reads the file from the extension. No setup.py needed.
  • license: Use an SPDX id such as MIT or Apache-2.0. Put the text in LICENSE. List it in license-files. Use hatchling >= 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 one Programming Language :: Python :: 3.X per version you test. Add Typing :: Typed if you ship py.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:function from the package under src/.

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

Response

  1. […] A Checklist for a New Python Package on GitHub: companion on naming, layout, metadata, and checks […]

Leave a Reply