SunnyWriteUps
Go back

How to Create Your First PyPI Package

Edit page

While older tutorials might instruct you to use setup.py, the modern, standardized approach uses pyproject.toml. This guide will walk you through the modern workflow from project creation to publishing.

How to Create and Publish Your Package

  1. Set Up Your Project Structure: The foundation. Create a new directory for your project. The best practice is to put your actual Python code inside a src directory to prevent accidental imports during testing.
my_package_project/
├── pyproject.toml
├── README.md
└── src/
    └── my_package/
        ├── __init__.py
        └── example.py

Your __init__.py can be empty, but it is required for Python to recognize the directory as a package.

  1. Create pyproject.toml: Replacing setup.py. The pyproject.toml file tells build tools how to package your project and defines metadata like the version, author, and dependencies. Here is a minimal example:
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my_unique_package_name"
version = "0.1.0"
authors = [
  { name="Your Name", email="your.email@example.com" },
]
description = "A short description of my first package"
readme = "README.md"
requires-python = ">=3.8"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

Note: The name must be entirely unique across all of PyPI.

  1. Build the Package: Generating the distribution archives. Next, you need to convert your source code into a distribution archive (a .tar.gz and a .whl file) that PyPI can host.

First, upgrade your build module, then run it:

python -m pip install --upgrade build
python -m build

This will create a dist/ directory containing two files. These are the files you will upload.

  1. Upload to TestPyPI: A safe sandbox for testing. Before publishing to the real PyPI, test the process using TestPyPI. This prevents you from permanently burning a version number if you make a mistake.

  2. Register an account on TestPyPI.

  3. Go to your Account Settings and create an API token (name it something like “Test Uploads”).

  4. Install Twine, the official PyPI upload tool:

python -m pip install --upgrade twine
  1. Upload your package:
python -m twine upload --repository testpypi dist/*

When prompted for a username, use __token__. For the password, paste the API token you generated.

  1. Publish to the Real PyPI: The final milestone. Once you have verified that everything looks correct on TestPyPI, repeat the process for the real PyPI:

  2. Register on PyPI.org.

  3. Generate an API token in your account settings.

  4. Run the upload command (without the test repository flag):

python -m twine upload dist/*

Congratulations! Your package is now live. Anyone can run pip install my_unique_package_name.

Pro Tips and Best Practices

Edit page
Share this post on:
Share this post via WhatsAppShare this post on FacebookShare this post on XShare this post via TelegramShare this post on PinterestShare this post via email
Previous Post
how to create your rust package
Next Post
Get Started with Kotlin How to Create Your First Android App