DEV Community

Cover image for Guide to publish your first PyPI library 🚀
Nitin Kumar
Nitin Kumar

Posted on

Guide to publish your first PyPI library 🚀

#python #pylib #tutorial #learning

👀 Do you also want to be included in that elite, mysterious, and totally brag-worthy list of contributors for a public PyPI package?
Yes? No? Still scrolling like it’s an Instagram reel? 📱
Cool, let’s fix that.

Why to create a py package? 🤔🐍

Before you start dreaming about PyPI fame (and GitHub stars 🌟 that your relatives won’t understand), pause for a reality check.

First, decide if your project is actually PyPI-worthy. Before touching configs, sanity-check that your project is reusable (no hardcoded paths, credentials, or “works only on my laptop” local files 💻❌) & has a clear entry point (functions/CLI).

If your script is “run once and forget” — PyPI is overkill 💀
If others (or future-you, after 3 months of memory loss 🧠) can reuse it → publish it 🚀

Think of it like the World Cup 🏏 — not every gully cricketer makes it to the squad, but the good ones do 😉
Same rules apply here.

📂 Folder structure needed (yes, structure matters)

Just like India’s budget announcements 📊 — boring, structured, but very important.

my_package/
│
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core.py
│       └── utils.py
│
├── tests/
│   └── test_basic.py
│
├── README.md
├── LICENSE
├── pyproject.toml
├── MANIFEST.in
└── .gitignore
Enter fullscreen mode Exit fullscreen mode

Mess this up, and PyPI will treat your package the way Twitter treats breaking news — harshly 😬🐦.

Content of pyproject.toml ❤️‍🔥

This is the heart of deployment.
Mess this up and your package dies faster than a government promise during elections 🗳️😌.

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

[project]
name = "my-package"
version = "0.1.0"
description = "Utility to validate API responses using schema rules"
readme = "README.md"
license = { file = "LICENSE" }
authors = [
    { name = "FIRSTNAME LASTNAME", email = "your@email.com" }
]
requires-python = ">=3.8"

dependencies = [
]

[project.urls]
Homepage = "https://github.com/yourname/my-package"
Enter fullscreen mode Exit fullscreen mode

Yes, every line matters.
No, PyPI doesn’t care if “it worked locally” 😌❌.

Contents of MANIFEST.in (don’t skip 🙏)

Ensures non-code files are packaged.
Skipping this is like hosting the World Cup final without a trophy 🏆 — technically possible, emotionally devastating.

include README.md
include LICENSE
Enter fullscreen mode Exit fullscreen mode

Without this, your PyPI page may break.
And users will judge you silently 🤐.

Key rules 🚨

There are some key rules while uploading your package on the PyPI website. These are non-negotiable — like ICC rules during finals 😤🏏:

  1. Name must be unique on PyPI (yes, utils, helpers, test-lib are already taken 😑)
  2. Version must follow semver
  3. Once uploaded → cannot overwrite the same version (PyPI never forgets 😈)

Requirements 📋

  1. A sample project which should adhere to these conditions
  2. Any code editor. I’m using VS Code here (because obviously 💙)
  3. A valid package name should be unique ⚠️
  4. A PyPI & test.pypi Account

; PyPI account can be created from here & tutorial for the same is in this youtube video

TestPyPI account can be created from here & tutorial for the same is in this youtube video

Yes, two accounts.
No, PyPI doesn’t trust you immediately — neither should it 😌🔐.

Steps to create & upload 🚀

Install build tools 🛠️ 

pip install --upgrade build twine
Enter fullscreen mode Exit fullscreen mode
  • build → creates wheel & source
  • twine → uploads to PyPI (your final boss 🎮)

Build your package 📦 

python -m build
Enter fullscreen mode Exit fullscreen mode

If this executes successfully (pray to the Python gods 🐍🙏), it will create:

dist/
├── my_package-0.1.0-py3-none-any.whl
└── my_package-0.1.0.tar.gz
Enter fullscreen mode Exit fullscreen mode

If it fails — congrats 🎉, you’re officially learning 🤨

Upload to testPyPI (optional but smart 🧠) 

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

Then install your uploaded package from testPyPI:

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

Test import + functionality here.
Break things now, not in production 😬🔥.

Upload to real PyPI 🌍 

twine upload dist/*
Enter fullscreen mode Exit fullscreen mode

; make sure dist/* uploads everything inside dist/.

And boom 💥 — Congratulations, you’ve just uploaded your own package! 🎉🎉
Take a moment. Screenshot it. Flex on LinkedIn 😎.

Something more 👀

Common mistakes ❌

❌ Hardcoded paths
❌ Forgot README / LICENSE
❌ Version conflict
❌ Import errors due to bad structure
❌ Uploading secrets accidentally (this one hurts the most 💀🔐)

Pro tips 💡

✅ Add CLI using entry-points
✅ Automate release via GitHub Actions
✅ Tag versions (v0.1.0)
✅ Add __version__ inside package
✅ Use ruff / black before publishing

Clean code = happy users 😊.

Hope you’ve successfully created your first package on PyPI 🐍🎯
Do share your package name in comments — let’s hype each other like World Cup fans 🇮🇳🏏.

I’ve recently committed pyshrink. Do check it out 👀✨.

Also, if you’ve got questions, confusion, or existential doubts about packaging — comment it out 💬😄.

Author
😎 Nitin Kumar

Top comments (0)