Launch a Python Library for Free: PyPI, TestPyPI and Trusted Publishing
Launch a Python library by making pip install work on a clean virtual environment, then publishing to PyPI after a rehearsal on TestPyPI, which is a separate registry with its own account. Package with a pyproject.toml, and set up trusted publishing so a GitHub workflow uploads releases without a stored token. Write a README whose first example runs as pasted, and announce in Python-specific newsletters and communities.
What does launching a library mean when nobody has installed it?
It means one sentence is true: someone who has never seen your code can create a fresh virtual environment, run pip install yourname, paste the first example from the README, and get the output you promised. Everything on this page serves that sentence. A library that fails it loses the reader at the very point they were most willing to try.
Do the test yourself before every announcement, on a different Python version from the one you develop on. If your metadata claims support for a version, run the tests on it. Declared support that has never been run is the most common kind of broken promise in a new package.
How should you choose the project name and the import name?
The packaging tutorial on packaging.python.org (read 13 November 2026) recommends that the directory holding your Python files match the project name, because it simplifies the configuration and is more obvious to the users who install it. Names on PyPI are shared by everyone, so search for yours before you commit to a brand around it. The tutorial itself adds your username to its example name so that learners do not collide with each other.
- Check the name is free on PyPI, and on the code host, and as a plain web search. Three clean results mean fewer later arguments.
- Do not plan to reclaim a name. PyPI’s name policy, based on PEP 541, covers abandoned projects and disputes, and it is a procedure with conditions, not a shortcut.
- Prefer one name. If the project name and the import name differ, say so in the first line of the README, since mismatches cause the first support questions.
Why rehearse on TestPyPI first?
PyPI’s packaging tutorial points you to a separate registry, TestPyPI, with its own registration, which also needs you to verify your email address before you can upload. Practising there means the real index stays clean while you discover that your README does not render, your license file is missing or your build includes files you did not intend. Treat anything uploaded to the real index as permanent, so every mistake you find on the rehearsal is one that never becomes a public version number.
- Build the package with the
buildtool and inspect the archive for files that should not be in it. - Upload to TestPyPI and open its project page to check that the description renders.
- Install from TestPyPI into a clean virtual environment and run your first example.
- Fix what broke, bump the version and repeat until it is boring.
How do you publish without leaving a token lying around?
PyPI documents trusted publishing, where a workflow on a supported service proves its identity through OpenID Connect and uploads without a long-lived password or token stored in the repository, and the same documentation covers attestations. The npm documentation describes the same idea for its own registry, and says the standard comes from the Open Source Security Foundation and is shared with PyPI and others.
For a first release the old way, a project-scoped API token pasted into a secret, is fine, but set up trusted publishing before your second. The setup is a few minutes on the project’s settings page and a short workflow file, and it removes the one credential that can leak. Make the workflow run only when you publish a release, and give it only the permissions it needs.
What does a Python reader look for in the README?
| Element | What it must do | Common mistake |
|---|---|---|
| One-line description | Say what problem it solves, in the words of the person who has it | A tagline about “modern, fast, simple” code |
| Install line | Be exactly what works, including any extras | Leaving out the extras the example needs |
| First example | Run when pasted and print something visible | An example that depends on a file you did not mention |
| Supported versions | List the Python versions you test | A range in the metadata that CI does not cover |
| Link to docs | Lead somewhere with a full reference | A docs site that is only the README again |
Add type hints to the public functions if you can. People who read your signatures in an editor will find the library easier to use, and it is one less thing to promise later. The README template gives you the section order.
Where do you tell the Python community?
PyCoder’s Weekly has a submission page that invites links to projects people are working on, with the caveat that it cannot promise to feature every one (read 13 November 2026). Submit a link when you have a release and a README that holds up, and treat a mention as a bonus. Then post a short story about the problem, in the community where that problem comes up, with the library linked at the end. A Show HN post fits, because the example is runnable.
A permanent public page helps too. When you launch your library on this board you verify one email and publish, with no queue, and the site link is a normal followed link. Builders who browse developer tool ideas and the Python project ideas guide are close to your audience, and where to launch Python packages lists further venues. If your package also ships a command, read the CLI tool playbook for the install side.
What should you track in the first weeks?
Watch for questions that repeat. Each one is a missing README line. Keep a short list of the issues filed by people you do not know, and note how many of them are installation problems, since a high share means the install test above was not honest enough. Download counts are available from PyPI’s statistics, but treat them as a rough signal, because mirrors and automated builds inflate them.
Frequently asked questions
Is it free to publish a package on PyPI?
The PyPI pages we read mention no publishing fee. You create an account, verify your email, build the package and upload it, and the packaging tutorial walks through each step. TestPyPI, the separate practice registry, needs its own account. Check PyPI’s current policies before you rely on this.
What is TestPyPI?
It is a separate instance of the package index meant for practising. It has its own registration and requires email verification before you upload. Use it to check that your build, metadata and README render correctly before publishing to the real index, where you should treat uploads as permanent.
What is trusted publishing on PyPI?
It lets a workflow on a supported service upload your package using OpenID Connect to prove its identity, so no long-lived token is stored in your repository. PyPI’s documentation describes how to add a trusted publisher to a project. Set it up before your second release.
Where can I announce a new Python library?
Submit a link to a Python newsletter such as PyCoder’s Weekly, which invites submissions but cannot promise to feature each one, post in the community where your problem comes up, try a Show HN, and add a free public page. Tag every link so you can see which one brought users.
Written by Post your build ideas with AI assistance and edited for this site. Where a page names another product, the facts came from that product’s own pages on the date shown above; terms change, so check them before you rely on them. About the publisher.