Creating an installable Python package is one of the best ways to turn reusable code into a professional tool. Instead of copying the same file between projects, you can organize your functions, add metadata, build distribution files, and install your own library with pip. Once the package is ready, you can share it privately, publish it to TestPyPI for testing, or release it on PyPI so other developers can install it.
This English version is adapted for developers who want a practical packaging workflow, not a literal translation. You will learn how to structure a package, create a pyproject.toml file, add package metadata, build source and wheel distributions, test installation locally, upload to TestPyPI, and prepare a clean release. If you are still learning Python fundamentals, start with this Python beginner guide and this article about modules and packages in Python.
What Is an Installable Python Package?
An installable Python package is a project that follows packaging conventions so tools such as pip can install it into a Python environment. The package includes your source code, metadata, version information, dependency declarations, and build configuration. After installation, users can import it like any other library.
The official Python Packaging User Guide is the authoritative reference for packaging projects. This tutorial keeps the same modern direction: use pyproject.toml, build distributions with the build package, and upload with twine. You do not need to start with legacy-only setup.py workflows for a basic modern package.
Why Package Your Python Code?
Packaging makes your code reusable. If you write the same helper functions for logging, data cleaning, API requests, file processing, or command-line automation, a package lets you install those helpers consistently across projects. It also encourages better organization because code must live in a clear directory structure with explicit dependencies and version numbers.
Packaging also improves collaboration. A teammate can install your tool with one command instead of copying files manually. A package can be versioned, tested, documented, and published. That makes it easier to fix bugs without breaking every project that uses the code. If you are building automation utilities, this guide to automation with Python is a useful next step.
Prepare a Clean Development Environment
Before creating the package, use a virtual environment. A virtual environment isolates dependencies so your packaging tools and test installs do not interfere with your global Python installation. This is especially important when testing whether the package installs correctly from scratch.
python -m venv .venv
# Windows PowerShell
.venvScriptsActivate.ps1
# macOS or Linux
source .venv/bin/activateThen install the basic packaging tools. The build package creates distribution files. twine uploads them to package indexes such as TestPyPI and PyPI. Keep pip updated so dependency resolution works predictably.
python -m pip install --upgrade pip build twineIf virtual environments are still confusing, review this guide to Python virtual environments. Packaging is much easier when each project has an isolated environment.
Recommended Project Structure
A small installable package needs a root directory, a source package, a metadata file, and documentation. The modern Python community often recommends a src layout because it helps catch import mistakes during development. For beginners, it may feel slightly more verbose, but it is a safer habit for real packages.
calculator-utils/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│ └── calculator_utils/
│ ├── __init__.py
│ └── operations.py
└── tests/
└── test_operations.pyThe folder under src contains the importable Python package. The file __init__.py marks the directory as a package and can expose public functions. The operations.py file contains your code. The tests directory is optional for a minimal example but strongly recommended for real projects. This guide to unit testing in Python explains the testing side.
Create the Package Code
Inside src/calculator_utils/operations.py, create a few simple functions. The goal is not to build a complex library. The goal is to make sure packaging, importing, building, and installing all work correctly.
def add(a: float, b: float) -> float:
"""Return the sum of two numbers."""
return a + b
def subtract(a: float, b: float) -> float:
"""Return the difference between two numbers."""
return a - bThen expose these functions from src/calculator_utils/__init__.py. This lets users import from the top-level package instead of reaching into the internal module path.
from .operations import add, subtract
__all__ = ["add", "subtract"]If you need a refresher on defining reusable behavior, read this guide to functions in Python. Good packages usually start with small, focused functions that do one job well.
Create pyproject.toml
The pyproject.toml file tells build tools how to package your project. It includes build-system requirements and project metadata such as name, version, description, Python version, authors, license, and classifiers. Modern packages can define this information without relying on an executable setup.py file.
[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"
[project]
name = "calculator-utils-yourname"
version = "0.1.0"
description = "A small example package for calculator utilities"
readme = "README.md"
requires-python = ">=3.9"
authors = [
{ name = "Your Name", email = "[email protected]" }
]
license = { text = "MIT" }
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent"
]
[project.urls]
Homepage = "https://github.com/yourname/calculator-utils"The package name must be unique on PyPI. A common beginner mistake is trying to publish a generic name that already exists. Add your username, organization name, or a distinctive project name. Once users depend on your package, changing the name becomes inconvenient, so choose carefully.
Write a Useful README
The README is often the first thing users see. It should explain what the package does, how to install it, and how to use it. Keep it direct. Include one short example that proves the package works. PyPI displays this file on your project page, so it affects whether developers trust your package.
# calculator-utils
A small example package for calculator utilities.
## Installation
pip install calculator-utils-yourname
## Usage
from calculator_utils import add
print(add(2, 3))Documentation does not need to be huge at the beginning, but it must be accurate. If the install command or import path is wrong, users will lose confidence immediately. For larger projects, include examples, configuration notes, changelog links, and contribution instructions.
Choose a License
A license tells users what they are allowed to do with your code. Without a license, many developers and companies will avoid using the package because the legal terms are unclear. The MIT License is common for small open-source Python packages because it is permissive and simple, but you should choose a license that matches your goals.
The Open Source Initiative license list is a useful place to compare common licenses. Add the license text to a LICENSE file and make sure your metadata matches it. Do not copy a license randomly without understanding what it allows.
Build the Distribution Files
After creating code, metadata, README, and license files, build the package. Run the command from the project root, where pyproject.toml is located.
python -m buildThis creates a dist directory containing files such as a source distribution and a wheel. The source distribution usually ends in .tar.gz. The wheel usually ends in .whl. Wheels are faster to install and are the standard distribution format for many packages.
If the build fails, check your folder names, package name, TOML syntax, README path, and Python version requirement. Many packaging problems come from small naming mismatches. If you see import errors while testing, this guide to fixing ImportError in Python can help.
Test the Package Locally
Before uploading anywhere, test the package locally in a clean virtual environment. This confirms that the built wheel installs correctly and that users can import the package. Do not rely only on the fact that imports work from the project root, because local imports can hide packaging mistakes.
python -m pip install dist/*.whl
python -c "from calculator_utils import add; print(add(2, 3))"On Windows PowerShell, wildcard handling may differ depending on the shell. You can also install by writing the exact wheel filename. The important point is to test the built artifact, not only the source tree. This catches missing files, wrong package discovery, and incorrect metadata earlier.
Upload to TestPyPI First
TestPyPI is a separate package index designed for testing uploads. Use it before publishing to the real PyPI. Create an account, generate an API token, then upload your package with twine. The official TestPyPI site is intended for exactly this kind of rehearsal.
python -m twine upload --repository testpypi dist/*When prompted, use __token__ as the username and paste the API token as the password. After uploading, install from TestPyPI in a clean environment. Because TestPyPI does not mirror every dependency from PyPI, simple packages without external dependencies are easier to test there.
python -m pip install --index-url https://test.pypi.org/simple/ calculator-utils-yournamePublish to PyPI
Once the TestPyPI upload works, repeat the upload for the official PyPI index. Create a PyPI account, enable two-factor authentication, generate an API token, and upload with twine. The package name and version must not already exist on PyPI. If you upload version 0.1.0, you cannot overwrite that same version later. You must publish a new version number.
python -m twine upload dist/*After publishing, install the package in a new environment using the normal pip install command. Then run a quick import test. This final check confirms that the public release is usable by other developers.
Versioning and Updates
Every release needs a unique version. A common convention is semantic versioning: MAJOR.MINOR.PATCH. Increase the patch version for small bug fixes, the minor version for backward-compatible features, and the major version for breaking changes. Even if your project is small, clear versioning helps users understand what changed.
When updating the package, change the version in pyproject.toml, rebuild the distribution files, and upload the new version. Delete the old dist files before rebuilding to avoid accidentally uploading stale artifacts. Keep a changelog if users depend on your package in real projects.
Common Packaging Mistakes
The first mistake is choosing a package name that already exists. The second is confusing the distribution name with the import package name. For example, the distribution might be calculator-utils-yourname, while the import path is calculator_utils. That difference is normal, but it must be documented clearly.
The third mistake is testing only from the project root. This can hide packaging errors because Python may import local files directly. The fourth mistake is forgetting to include important files such as README, license, or package modules. The fifth mistake is publishing secrets, tokens, local paths, or private configuration files by accident. Always inspect your repository and distribution contents before uploading.
Final Checklist
Create a virtual environment. Use a clean project structure. Put importable code under a package directory. Define metadata in pyproject.toml. Write a useful README. Add a license. Build with python -m build. Test the wheel locally. Upload to TestPyPI first. Install from TestPyPI in a clean environment. Then publish to PyPI only after the test release works.
Learning how to create an installable Python package turns your code into something reusable, shareable, and easier to maintain. It is a practical step from writing scripts toward building real developer tools. Once you understand packaging, every useful helper function can become part of a cleaner and more professional Python workflow.
