How to Host Your Python Package on PyPI in 2024

Ever written a handy Python script that you think others might use? Turning it into a proper PyPI package is easier than you think. Let me walk you through the exact steps we use here at PythonSkillset to get your code up on the official Python package index.

What You'll Need Before Starting

First things first - make sure you have these ready:

• A working Python package (even a simple one will do)
• Python 3.6 or newer installed
• Pip installed (it usually comes with Python)
• A PyPI account (sign up at pypi.org - it's free)
• Twine (we'll install this in a moment)

Step 1: Structure Your Package Properly

Your package needs a specific folder structure. Here's what we recommend based on what works well:

your-package-name/
├── your_package_name/
│   ├── __init__.py
│   └── your_code.py
├── tests/
│   └── test_your_code.py
├── README.md
├── LICENSE
├── pyproject.toml
├── setup.cfg
└── setup.py

Notice the underscore in your_package_name - PyPI handles underscores better than hyphens in import names.

Step 2: Create the Essential Configuration Files

The pyproject.toml File

This is now the standard way to configure Python packages. Here's a template:

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "your-package-name"
version = "0.1.0"
authors = [
    { name="Your Name", email="your@email.com" },
]
description = "A short description of your package"
readme = "README.md"
license = { file="LICENSE" }
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.urls]
Homepage = "https://github.com/yourusername/your-package"
Repository = "https://github.com/yourusername/your-package.git"

The setup.cfg File

[metadata]
name = your-package-name
version = 0.1.0
description = A short description
long_description = file: README.md
long_description_content_type = text/markdown
url = https://github.com/yourusername/your-package
license = MIT

[options]
packages = find:
python_requires = >=3.6

Step 3: Build Your Package

Open your terminal and navigate to your package directory:

cd /path/to/your-package-name

First, make sure you have the latest building tools:

python -m pip install --upgrade build

Now build your package:

python -m build

This creates two files in a dist/ folder: - A .tar.gz source distribution - A .whl wheel file (the modern distribution format)

Step 4: Upload to PyPI

Install Twine if you haven't already:

pip install twine

For testing first (always a good idea), use TestPyPI:

twine upload --repository-url https://test.pypi.org/legacy/ dist/*

When you're ready for the real thing:

twine upload dist/*

You'll be prompted for your PyPI username and password. Pro tip: use a PyPI API token instead of your password. You can generate one from your PyPI account settings.

Step 5: Verify Your Package

Test it immediately by installing from PyPI:

pip install your-package-name

Then in your Python environment:

import your_package_name
# Or use the specific module
from your_package_name import your_module

Common Pitfalls to Avoid

At PythonSkillset, we've seen developers make these mistakes:

1. Duplicate names - Check if your package name is already taken on PyPI
2. Missing README - Without a good README, nobody will understand what your package does
3. Ignoring version numbers - Use proper semantic versioning (major.minor.patch)
4. Forgetting to update - When you make changes, remember to bump your version number and rebuild

The Quick Cheat Sheet

Here's the short version for when you're in a hurry:

# One-time setup
pip install build twine

# For each release
python -m build
twine upload dist/*

# Verify
pip install --upgrade your-package-name

Real Example from PythonSkillset

We recently published a small package called "textstatify" - it analyzes text readability. The whole process took about 30 minutes from code to PyPI. The key was having clean documentation and proper versioning from day one.

Remember: good packages solve real problems. Focus on making something useful, and the hosting part is just paperwork.

Ready to share your Python code with the world? Start with that first step - structure your package right - and you'll be on PyPI before you know it.