DEV Community

Cover image for How to Publish Your Python Package to PyPI (Modern Guide with `pyproject.toml`)
Tima
Tima

Posted on

How to Publish Your Python Package to PyPI (Modern Guide with `pyproject.toml`)

#python #pypi #packaging #opensource

Publishing your own Python package is a milestone for any developer. It turns your code into something the community can install with a simple pip install. This guide is a quick start for beginners who want to publish their first package using the modern pyproject.toml approach.

Why PyPI Matters

  • Central hub: PyPI is the official package index for Python, similar to npm for JavaScript.
  • Easy installs: With one command, you can pull in frameworks like Django or libraries like requests.
  • Standardization: Packaging ensures consistent distribution and deployment across projects. 
pip install django
Enter fullscreen mode Exit fullscreen mode

Setting Up the Basics

  1. Install Python: Download from python.org. Pip comes bundled.
  2. Create a project directory: Example: UsefulPackage/.
  3. Set up a virtual environment: 
python -m venv .venv
Enter fullscreen mode Exit fullscreen mode
  1. Register accounts:
    • PyPI for production.
    • TestPyPI for practice (recommended for beginners).

Minimal Project Structure

Your package should look like this:

UsefulPackage/
 ├── .venv/
 ├── src/
 │    └── useful_package_timthewebmaster/
 │         ├── __init__.py
 │         └── main.py
 ├── LICENSE
 ├── pyproject.toml
 ├── dist/
Enter fullscreen mode Exit fullscreen mode

Configuring pyproject.toml

This file defines how your package is built and its metadata. Minimal example:

[build-system]
requires = ["hatchling >= 1.26"]
build-backend = "hatchling.build"

[project]
name = "useful-package-timthewebmaster"
version = "0.0.1"
authors = [
  { name="Tim The Webmaster", email="timachuduk@gmail.com" }
]
license = "MIT"
Enter fullscreen mode Exit fullscreen mode

👉 You can add classifiers, dependencies, keywords, and URLs to make your package more discoverable. See PyPI classifiers for options.

Building the Package

Install the build tool:

pip install build
Enter fullscreen mode Exit fullscreen mode

Generate distributions:

python -m build
Enter fullscreen mode Exit fullscreen mode

This creates .tar.gz and .whl files inside dist/.

Uploading to PyPI

Install Twine:

pip install twine
Enter fullscreen mode Exit fullscreen mode

Upload to TestPyPI:

python -m twine upload --repository testpypi dist/*
Enter fullscreen mode Exit fullscreen mode

Upload to PyPI:

python -m twine upload dist/*
Enter fullscreen mode Exit fullscreen mode

You’ll need an API token from your PyPI account.

Testing Your Package

Install from TestPyPI:

pip install --index-url https://test.pypi.org/simple/ useful-package-timthewebmaster
Enter fullscreen mode Exit fullscreen mode

Or from PyPI directly:

pip install useful-package-timthewebmaster
Enter fullscreen mode Exit fullscreen mode

Run your project and confirm imports work correctly.

Final Thoughts

Publishing to PyPI is more than distribution—it’s about joining the ecosystem. By sharing your package, you contribute to the collective toolbox of developers worldwide. Start small, iterate, and soon you’ll have a portfolio of packages that reflect your coding style and creativity.

💡 Pro tip: Use TestPyPI for practice. It keeps the main index clean and gives you confidence before going public.

Tags

#python #pypi #packaging #opensource #developers

Discussion

Have you published a package to PyPI before?

What challenges did you face during the process?

Further Reading

Top comments (0)