Launch guideDeveloper tools
How to launch a Python library
A Python library launch is judged on its PyPI page, which is built from your package metadata and README. If the README doesn't render (a common problem with reStructuredText extensions), the page shows raw markup on day one. Set up trusted publishing from CI, check the README with twine, and launch where Python developers already share tools.
Updated · platform facts checked against the official docs linked below
At a glance
Where people find Python librarys
- PyPI search: Classifiers and keywords help filtering; the README is the page.
- Python communities: Subreddits, Discords and forums for Python and for your domain (data, web, ML).
- Newsletters and podcasts: Python weekly newsletters accept tool submissions; check each one's process.
- Hacker News (Show HN): For libraries with a strong demo.
- GitHub: Examples, notebooks and issues are how many people evaluate a library.
Assets to prepare
| Asset | Spec or guidance |
|---|---|
| pyproject.toml metadata | Name, version, description, readme with content type, license, classifiers, project URLs. |
| README | Markdown or valid reStructuredText; install, 10-line example, links to docs.[1] |
| Classifiers | Python versions, license, development status, topic. |
| Docs site | Hosted on your own domain or a docs host, with a quick start. |
| Notebook or Colab demo | For data and ML libraries, a runnable notebook. |
Store and listing rules
What the platform itself says, with a link to the page we checked.
- PyPI renders plain text, reStructuredText without Sphinx extensions, or Markdown (GFM by default). Invalid reST shows as raw source.[1]
- Trusted publishing exchanges a CI identity token for a short-lived PyPI token, so you don't store API tokens in CI.[2]
A 4-week launch timeline
Week 1 · four weeks out
- Fill pyproject.toml metadata and classifiers.
- Write the README example first.
- Reserve the name on PyPI with a real, working release.
Week 2 · three weeks out
- Set up trusted publishing from GitHub Actions.
- Run
twine checkin CI. - Publish a pre-release for testers.
Week 3 · two weeks out
- Write docs for the top three tasks.
- Build a runnable notebook or example repo.
- Prepare community posts.
Week 4 · launch week
- Release 1.0 with changelog.
- Submit to relevant newsletters.
- Add to LaunchRanked with a docs link.
Launch-day checklist
- Publish the release and check the PyPI page renders.
- Post the example in Python and domain communities.
- Answer issues and questions the same day.
After launch: SEO steps
Launch boards reset; search pages don't. These steps keep people finding you after launch week.
- Write docs pages for "how to {task} in Python" searches.
- Publish comparison pages with the libraries people mention.
- Keep docs versioned and indexable for the latest version.
Common mistakes
- README using Sphinx roles that break PyPI rendering.
- Squatting a name with an empty package.
- No classifiers, so filters skip the package.
Templates for this launch
- Release notesRelease notes for a notable launch or version: what's new, why it matters, how to use it, upgrade steps and known issues, with a filled example.
- Changelog entryA changelog entry template grouped by Added, Changed, Fixed and Removed, written for users rather than commit logs, with a filled example.
- Show HN postA Show HN template that follows Hacker News rules: a plain title, a link people can try, and a first comment on why you built it and how it works.
FAQ
Why does my README look broken on PyPI?
PyPI's renderer doesn't support Sphinx extensions in reStructuredText. Use Markdown or plain reST, set the content type, and run twine check before uploading.
What is PyPI trusted publishing?
A way to publish from CI using OpenID Connect: your CI's identity token is exchanged for a short-lived PyPI token, so there's no long-lived API token to leak.
Where do Python developers find libraries?
PyPI, GitHub, Python newsletters and communities for their domain. Search brings them later through docs and tutorials.
Should I publish docs on my own domain?
It helps with search and gives you a place to link from launch posts. Any stable docs host works if the pages are indexable.
Sources
Checked . Platforms change their rules; open the source before you rely on a number.
Related launch guides
- How to launch an npm packageLaunch an npm package: package.json fields, provenance and trusted publishing, a README that sells, and where JavaScript developers look.
- How to launch a CLI toolLaunch a command-line tool: install paths (Homebrew tap vs core, winget, npm, pip), terminal GIFs, Show HN and docs that rank for the problems it solves.
- How to launch an open-source projectLaunch an open-source project: README and repo setup, GitHub topics and social preview, Show HN rules, awesome lists, and docs that rank on Google.
- How to launch a developer APILaunch a developer API: time to first call, docs, OpenAPI, a Postman public workspace, keys and limits, and docs pages that rank.