Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 38 ยท Getting Started

What Is Python Packaging?

Understand modules, packages, distributions, wheels, sdists and PyPI, and how a folder of code becomes something other people can install with one command.

Sooner or later every Python project hits the same questions. How do I share this script with a colleague? How do I use someone else's code without copying files by hand? Why does my program work on my laptop and fail on the server? Packaging is the set of conventions and tools that answers all of them: how code is organized, described, built, shipped and installed.

This course, "Python Packaging and Tooling", walks through the whole life cycle: environments, pyproject.toml, building wheels, publishing, dependency management, linting, testing, CI and containers. Be aware of one honest limit up front: the lessons run inside your browser, where there is no real shell, no pip command, no venv module and no network access to PyPI beyond a few pure-Python wheels. Commands you would type in a terminal appear as read-only bash blocks. Everything that can run in Python (parsing pyproject.toml, version comparison, building a real wheel with zipfile, installing it, reading its metadata) is a live editor that really executes.

Four words that sound alike

People mix these up constantly, so fix the vocabulary first.

  • A module is one Python file you can import, such as utils.py.
  • A package (an import package) is a directory of modules, usually with an __init__.py, that you import by name, such as import requests.
  • A distribution (a distribution package) is the downloadable thing: a versioned archive with metadata, such as requests 2.32.0. One distribution can contain several import packages, and the distribution name does not have to match the import name (pip install scikit-learn, then import sklearn).
  • A project is the source tree you develop, which you turn into distributions.
Python Modules, packages and distributions in a live session

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The two names matter because you use them in different places. You write the distribution name in pip install and in your dependency lists. You write the import name in your source code.

What happens when you pip install something

An index such as the Python Package Index (PyPI) stores many releases of each project. Each release has one or more files: wheels (.whl, ready to unpack) and usually one sdist (source distribution, a .tar.gz that must be built first). An installer picks the best file for your Python and platform, resolves its dependencies, and unpacks everything into a directory named site-packages, where Python's import system can find it.

flowchart LR
    A["Your source tree<br/>(project)"] -- "build" --> B["Wheel + sdist<br/>(distributions)"]
    B -- "upload" --> C["Index<br/>(PyPI)"]
    C -- "download + resolve" --> D["Installer<br/>(pip, uv)"]
    D -- "unpack" --> E["site-packages<br/>in an environment"]
    E -- "import" --> F["Your program runs"]

A package travels from author to user in five steps. Each step has a standard format, so different tools can cooperate.

The important part is the word standard. Years ago, setup.py scripts ran arbitrary code to do everything, and each tool had its own habits. Today these are agreed formats, written down as numbered PEPs (Python Enhancement Proposals) and maintained on packaging.python.org as the "PyPA specifications". You will meet the key ones in this course: pyproject.toml (PEP 517, 518, 621), wheels (PEP 427), version rules (PEP 440), and the simple index API (PEP 503).

Why not just copy files?

Copying works for one script. It stops working when:

  1. You need other people's code. A single data project may use dozens of libraries, and each of those uses more. Doing that by hand is hopeless.
  2. Versions matter. Library A needs requests >= 2.30 while library B needs requests < 2.29. Someone has to detect that.
  3. Two projects need different versions of the same library on one computer. That is the job of virtual environments.
  4. Code needs more than Python files. Data files, compiled extensions, command-line scripts and licenses must travel together.
  5. You want to upgrade safely. Metadata with version numbers lets tools say "this release is newer, and it still works with your Python."

The metadata trail

Every installed distribution leaves a small .dist-info folder next to its code. It records the name, version, dependencies, license, entry points and a list of installed files with hashes. Python can read it back at any time with importlib.metadata.

Python Reading the metadata an installed package left behind

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

That metadata is the same text format that a build tool writes into a wheel when you publish. In Project Metadata Fields you will write it yourself.

The cast of tools

You will hear many names. Roughly they fall into groups:

Job Common tools
Install packages pip, uv, pipx
Isolate environments venv, virtualenv, uv venv
Describe a project pyproject.toml
Build distributions build, uv build, build backends (setuptools, hatchling, flit-core, pdm-backend, maturin)
Upload twine, uv publish, trusted publishing from CI
Manage dependencies and locks pip-tools, uv, poetry, pdm

A later lesson, The Tooling Landscape, compares them in detail so you can choose with confidence.

Packaging terms are used loosely in blog posts. "Package" can mean a folder, a distribution or a PyPI project. When something confuses you, ask which of the four words above it is really about.

A first look at the whole journey

Here is the entire life of a small library, as terminal commands. Do not memorize them; every step gets its own lesson.

Terminal
python -m venv .venv              # 1. isolate an environment
source .venv/bin/activate         #    (Windows: .venv\Scripts\activate)
pip install build twine           # 2. install tools
python -m build                   # 3. create dist/*.whl and dist/*.tar.gz
twine check dist/*                # 4. check the metadata renders
twine upload dist/*               # 5. publish to PyPI
pip install mylibrary             # 6. anyone can now install it

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You run pip install scikit-learn and then import sklearn. Which statement is correct?

    pip installs a distribution by its distribution name. The import package it provides can have a different name. They are independent.
  2. 2. Which file type is a ready-to-unpack archive that an installer can usually just copy into site-packages?

    A wheel is a built distribution. An sdist contains source and must be built first, which can run compilers and take much longer.
  3. 3. Where does an installed distribution record its version, dependencies and file list?

    Each installed distribution keeps a .dist-info directory (METADATA, RECORD, WHEEL, entry_points.txt). importlib.metadata reads it.
  4. 4. Why are virtual environments needed?

    An environment has its own site-packages, so projects do not fight over versions.

Summary

  • A module is a file, a package is a directory of modules, a distribution is the installable archive, and a project is your source tree.
  • Distribution name (used with pip install) and import name (used with import) can differ.
  • Releases are shipped as wheels (built, fast to install) and sdists (source, built on install).
  • Installed packages leave .dist-info metadata that importlib.metadata can read.
  • Standards (PEPs and PyPA specs) let many tools cooperate on the same formats.
  • In this course, shell commands are read-only and Python logic runs live.

Next: Modules, Packages and the Import System