How to Create Your First Python Package and Publish on PyPI: A Complete Beginner’s Guide

← Back to Home

 

How to Create Your First Python Package and Publish on PyPI (Expanded Guide)

---

Introduction

Publishing your own Python package can be a rewarding experience. It lets you share your code with the global community, showcase your skills, and even simplify your own projects by reusing code easily. In this guide, I’ll take you through the full process—from creating your package structure to uploading it on PyPI—with practical tips and common pitfalls to avoid.

---

What Is a Python Package and Why Publish One?

A Python package is a collection of modules organized in directories that allow others to reuse your code by simply installing it via pip. Publishing on PyPI (Python Package Index) is like putting your package in the official Python library store, making it easy for anyone to find and install it.

Why publish?

• Share useful tools with the world

• Build your portfolio and credibility

• Encourage collaboration and contributions

• Manage your own code efficiently across projects

---

Step 1: Set Up Your Package Structure

Organize your files clearly. Here’s a recommended folder structure:

my_package/
├── my_package/
│   └── __init__.py
├── tests/
│   └── test_basic.py
├── setup.py
├── README.md
└── LICENSE

What these files do:

• my_package/ — This is where your package code lives.

• __init__.py — This file can be empty or include package initialization code.

• tests/ — Always good to include some tests to ensure your package works.

• setup.py — Contains metadata and instructions for packaging.

• README.md — Explains what your package does.

• LICENSE — Open-source licenses define how others can use your code (MIT, Apache, etc.).

Tip: Adding tests makes your package more professional and reliable.

---

Step 2: Write Your Package Code

Create a simple function to start. For example, in my_package/__init__.py:

def greet(name):
    """Return a friendly greeting."""
    return f"Hello, {name}! Welcome to my package."

Tip: Write clear docstrings and comments to help users understand your code.

---

Step 3: Prepare setup.py for Packaging

This script tells Python how to build and install your package.

Example:

from setuptools import setup, find_packages

setup(
    name='my_package',  # Choose a unique package name on PyPI
    version='0.1.0',
    author='Your Name',
    author_email='your.email@example.com',
    description='A simple greeting package',
    long_description=open('README.md').read(),
    long_description_content_type='text/markdown',
    url='https://github.com/yourusername/my_package',
    packages=find_packages(),
    classifiers=[
        'Programming Language :: Python :: 3',
        'License :: OSI Approved :: MIT License',
        'Operating System :: OS Independent',
    ],
    python_requires='>=3.6',
)

Pro tip: Use find_packages() to automatically discover subpackages.

---

Step 4: Write a Helpful README.md

Your README is often the first thing users see.

Include:

• What your package does

• Installation instructions

• Basic usage examples

• Links to documentation or source code

Here’s a mini template you can adapt:

# my_package

A simple Python package that greets users.

## Installation

```bash
pip install my_package

Usage

from my_package import greet

print(greet("Alice"))

---

## Step 5: Choose a License

Open source licenses tell users what they can do with your code. Popular licenses include:

- **MIT License:** Very permissive, allows almost anything.
- **Apache 2.0:** Includes patent protections.
- **GPL:** Requires derivatives to be open source too.

Choose a license and add a `LICENSE` file in your project.

---

## Step 6: Build Your Package

Before publishing, install the latest build tools:

```bash
pip install --upgrade setuptools wheel

Then run:

python setup.py sdist bdist_wheel

This creates .tar.gz and .whl files in the dist/ folder.

---

Step 7: Test Locally (Optional but Recommended)

Install your package locally to test before uploading:

pip install dist/my_package-0.1.0-py3-none-any.whl

Then run:

from my_package import greet
print(greet("Test User"))

---

Step 8: Upload Your Package to PyPI

Install Twine:

pip install --upgrade twine

Create an account on PyPI if you haven’t already.

Upload your package:

twine upload dist/*

Enter your credentials when prompted.

---

Step 9: Celebrate and Share!

Your package is now live! You can install it via:

pip install my_package

Share your package on social media, forums, or developer communities to get feedback and contributions.

---

Common Pitfalls to Avoid

• Package name conflicts: Check PyPI to ensure your package name is unique.

• Forgetting __init__.py: Without this file, Python won't recognize your folder as a package.

• Ignoring dependencies: List dependencies in setup.py if your package requires other packages.

• Skipping tests: Always test your package thoroughly before publishing.

---

Conclusion

Publishing your first Python package might feel complex at first, but with this guide, you’re well-equipped to share your work with the Python community. Keep refining your package, writing tests, and engaging with users to make it even better!

← Back to Home