Python Developer Tooling Handbook – Packaging

Why Doesn't the Authoritative Python Packaging Guide Mention the Best Thing that's Happened to Python Packaging?

Tim Hopper — Thu, 27 Feb 2025 14:56:00 +0000

uv is the most widely adopted new Python tool in years, yet the Python Packaging User Guide (PPUG) at packaging.python.org makes no mention of it. The reason has less to do with uv and more to do with how Python packaging governance works.

What uv Does

uv delivers 10-100x faster package operations than pip while consolidating functionality previously spread across multiple utilities (pip, pip-tools, virtualenv, pyenv, and more) into a single tool. Since its introduction in early 2024, it has become the default recommendation in many Python teams and communities.

Briefcase

Tim Hopper — Thu, 07 May 2026 07:15:39 -0400

Briefcase is the only mainstream Python packaging tool that ships to iOS and Android. It also packages applications for macOS, Windows, Linux, and the Web, producing platform-specific artifacts (.app/DMG, MSI, .deb/.rpm/AppImage/Flatpak, Xcode project, Gradle project, PyScript/Pyodide site) from a single pyproject.toml configuration.

Briefcase is part of the BeeWare project and is the packaging companion to Toga, BeeWare’s cross-platform GUI toolkit. Briefcase does not require Toga; it packages any Python application, GUI or otherwise. Install it with uv tool install briefcase or pipx install briefcase; the BSD 3-Clause license imposes no restrictions on applications it packages.

build: Python Package Build Frontend

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

build is a PEP 517-compliant Python package builder developed by the Python Packaging Authority (PyPA). It provides a standardized interface for building Python packages using any compliant build backend, serving as a simple frontend tool that executes the build process defined by backends like setuptools, flit, or hatchling.

Core Functionality

Build Operations

Source Distributions: Creates sdist packages containing source code
Binary Distributions: Builds wheel packages for direct installation
Backend Compatibility: Works with any PEP 517-compatible build backend
Isolated Builds: Manages build dependencies in separate environments
Cross-Platform Support: Functions consistently across operating systems

Command Interface

# Build both wheel and sdist
python -m build

# Build only a wheel
python -m build --wheel

# Build only a source distribution
python -m build --sdist

# Build in a specified directory
python -m build /path/to/project

# Build with specific Python interpreter
python -m build --python-executable /path/to/python

Technical Design

build operates using a straightforward process flow:

Build a Python library with a C extension

Tim Hopper — Wed, 29 Apr 2026 07:06:23 -0400

Python handles strings well. C handles them faster. In this tutorial, you’ll write three string functions in C, compile them into a shared library, and call them from Python using cffi. The result is a normal Python package that anyone can import.

Prerequisites

You need two things installed:

uv (installation guide)
A C compiler

Most macOS and Linux systems already have a C compiler. Check by running:

Build a Python library with a C++ extension

Tim Hopper — Fri, 08 May 2026 03:18:44 -0400

Python handles most tasks well, but numerical code and tight loops can hit its performance ceiling. C++ removes that ceiling. This tutorial walks you through creating a Python package where the performance-critical code lives in C++, compiled into a native extension module that Python imports like any other module.

You’ll use three tools together:

uv manages the Python project, dependencies, and virtual environment
scikit-build-core is the build backend that drives CMake to compile C++ code into a Python extension module
pybind11 is the C++ library that bridges C++ and Python, letting you write C++ functions callable from Python

Prerequisites

uv installed (installation guide)
A C++ compiler (g++ or clang++)
CMake 3.15 or later

Most macOS and Linux systems ship with a C++ compiler. On macOS, install the Xcode Command Line Tools (xcode-select --install). On Ubuntu/Debian, install the build-essential and cmake packages.

Build a Python library with a Rust extension

Tim Hopper — Fri, 15 May 2026 11:45:25 -0400

Python is flexible and productive, but sometimes a function needs to run faster than Python allows. Rust gives you that speed with memory safety and no garbage collector. This tutorial walks you through creating a Python package where the performance-critical code lives in Rust, compiled into a native extension module that Python imports like any other module.

You’ll use three tools together:

uv manages the Python project, dependencies, and virtual environment
maturin is the build backend that compiles Rust code into a Python extension module
PyO3 is the Rust library that bridges Rust and Python, letting you write Rust functions callable from Python

Prerequisites

uv installed (installation guide)
Rust installed via rustup

Verify both are working:

cibuildwheel: Cross-Platform Python Wheel Builder

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

cibuildwheel is a CI tool that builds Python wheels for multiple platforms, architectures, and Python versions from a single configuration. It runs on CI servers (GitHub Actions, GitLab CI, Azure Pipelines, CircleCI, and Cirrus CI), automating the work of compiling C/C++/Rust/Cython extensions and producing manylinux/musllinux-compliant wheels.

Note

Conda Package

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

A conda package is a compressed archive containing pre-built binaries, library code, metadata, and dependency information for installation through conda channels. It serves the same role in the conda ecosystem that a wheel serves on PyPI, with one critical difference: conda packages can bundle software from any language (Python, R, C++, Fortran, Julia), not just Python.

Package Formats

The conda ecosystem recognizes two archive formats, referred to as v1 and v2.

cx_Freeze

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

cx_Freeze is a Python application freezer that packages a Python program and its dependencies into a self-contained directory or executable. It targets Windows, macOS, and Linux from the same configuration and ships native commands for producing each platform’s preferred installer format. Recent releases add experimental support for freezing free-threaded CPython builds. Install it with uv tool install cx_Freeze or pipx install cx_Freeze.

When to Use cx_Freeze

cx_Freeze fits projects whose deliverable is an installer rather than a raw binary. Its bdist_msi, bdist_dmg, bdist_appimage, and bdist_deb commands produce platform-native installers in one step, without a second packaging tool like WiX, dmgbuild, or dpkg-deb. Most other freezers stop at a folder or single executable and leave installer generation to the user.

distutils: Python's Original Build System

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

distutils was a standard library module that provided the original mechanism for building and distributing Python packages. It defined the setup.py-based workflow that became the foundation of Python packaging for over two decades.

What It Did

distutils handled package building, installation, and distribution through a setup.py script:

from distutils.core import setup

setup(
    name="example",
    version="1.0",
    py_modules=["example"],
)

Running python setup.py install would copy modules into the correct location on the target system. Running python setup.py sdist would produce a source distribution archive.

Does Poetry Support Python Standards for Dependency Management?

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

Poetry 2.0 supports standard PEP 621 project metadata in pyproject.toml. Before version 2.0, Poetry used only its own tool.poetry configuration format, but the 2.0 release adopted the standard project section.

Poetry now offers two configuration approaches. You can use project.dependencies for standard dependency declarations or tool.poetry.dependencies for Poetry-specific features, and you can combine both when needed.

Standard metadata makes projects more portable between build tools and aligns with emerging packaging standards.

Related Handbook Pages

Learn More

Flit: Python Package Build and Publish Tool

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

Flit is a Python packaging tool designed to be simple to use. Flit provides flit init to create a new package, flit publish for publishing to PyPI, automatically includes data files in the package, and fetches the package version number from the __init__.py file.

Flit does not support advanced packaging functionality like building C extensions. It also doesn’t provide a CLI for managing virtual environments or dependencies; the user creates their own virtualenv and adds dependencies to the pyproject.toml file manually.

Hatch: Python Project Manager

Tim Hopper — Wed, 06 May 2026 06:23:54 -0400

hatch is a Python project management tool maintained by the Python Packaging Authority (PyPA). It handles virtual environment management, dependency resolution, project scaffolding, and publishing through a unified interface that follows Python packaging standards. Its build backend, hatchling, is one of the most widely used on PyPI.

When to Use Hatch

Hatch suits library authors who want a single, standards-compliant tool covering scaffolding, building, publishing, and multi-version testing. Its environment matrix system runs tests across Python versions and dependency sets without a separate tool like tox or nox. PyPA governance backs the project.

How do I ship a Python application to end users?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Python usually ships an environment rather than a native executable. It ships as code plus an interpreter plus dependencies, which is why distribution gets harder the moment the users are not Python developers themselves. The real question is not whether Python can be shipped well. It can. The question is which delivery shape fits the audience: an install command, a bundled app, a container image, or something that stops being Python at all.

How do uv and Poetry compare?

Tim Hopper — Fri, 10 Apr 2026 13:36:01 -0400

Poetry and uv both manage Python projects through pyproject.toml, create lockfiles, and handle virtual environments. Poetry has been the default recommendation for years; uv, built by Astral, arrived in 2024 with broader scope and faster dependency resolution. They differ in how.

Scope

Poetry handles dependency management, virtual environments, building, and publishing. Everything else it delegates. A different Python version requires pyenv. Running a CLI tool without installing it globally requires pipx.

How Python Package Formats Evolved: From tar.gz to .whl

Tim Hopper — Sat, 11 Apr 2026 17:25:27 -0400

In 2000, installing a third-party Python package meant downloading a tarball, extracting it, and running python setup.py install. There was no dependency resolution, no uninstall command, no record of what got installed where. Removing a package meant deleting files by hand and hoping none were missed.

Twenty-five years later, uv pip install numpy fetches a pre-built binary wheel and drops it into place in under a second. The journey between those two moments is a story of each generation solving one problem while inadvertently creating the next.

How to add dynamic versioning to uv projects

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Dynamic versioning generates version numbers from Git tags instead of requiring manual updates to a static version string in pyproject.toml. The release workflow becomes a single git tag command: the build backend reads the tag, and the wheel and source distribution filenames pick up the matching version automatically.

This guide uses uv-dynamic-versioning, a hatchling plugin that ships a sensible default configuration for uv projects.

Prerequisites

A Git repository for your Python project with at least one commit
uv installed on your system
A src/your_package/ layout (the default for uv init --package)

Configure the build system

Update pyproject.toml to use uv-dynamic-versioning as a build backend dependency:

How to Build Multi-Platform Wheels with cibuildwheel

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Python packages with compiled extensions (C, C++, Rust, Cython) need platform-specific wheels so users can install them without a compiler. cibuildwheel automates building these wheels across operating systems, architectures, and Python versions in CI.

This guide sets up a GitHub Actions workflow that builds wheels for Linux, macOS, and Windows, then publishes them to PyPI.

Prerequisites

A Python project with a compiled extension and a PEP 517-compliant build backend (setuptools, scikit-build-core, maturin, etc.)
A [build-system] table in pyproject.toml
A GitHub repository
A PyPI account with trusted publishing configured for the repository

Configure cibuildwheel

Add a [tool.cibuildwheel] section to pyproject.toml. This example targets CPython 3.11 through 3.13, skips 32-bit builds, and runs pytest after each wheel build:

How to convert a script with requirements.txt to PEP 723 inline metadata

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

A standalone Python script paired with a requirements.txt is the old way of saying “this script needs these libraries.” PEP 723 replaces the sidecar file with a TOML block embedded in the script itself, and uv reads that block to install dependencies into a temporary virtual environment on every run.

Translate the requirements.txt into inline metadata

Point uv add --script at the existing requirements file. uv reads it and prepends a PEP 723 block to the script:

How to Create and Distribute a Python CLI Tool

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

pyproject.toml lets you attach any Python function to an executable command name via [project.scripts]. When someone installs the package, their package manager creates a wrapper script that calls that function. With uvx, users can run the tool without even installing it first.

Tip

How to fix the "externally-managed-environment" error

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Running pip install on a system Python protected by PEP 668 produces this error:

error: externally-managed-environment

× This environment is externally managed

The fix depends on what was being installed.

Installing project dependencies

Use uv to create a project with its own virtual environment:

How to format pyproject.toml with taplo

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

uv does not include a built-in formatter for pyproject.toml. Taplo is a TOML formatter and validator that keeps pyproject.toml files consistently styled across a project.

Format with uvx

Run taplo as a one-off command without installing it:

uvx taplo fmt pyproject.toml

To check formatting without modifying files (useful in CI):

How to Host Your Own Python Package Index

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

A self-hosted Python package index can save a team from PyPI outages, vendor lock-in, or restricted networks, but it also gives that team another service to run. Three tools cover almost every use case: devpi for production multi-team setups, pypiserver for a small team that needs somewhere to put internal-greeter-0.1.0.whl, and bandersnatch for full PyPI mirrors on networks that cannot reach pypi.org.

Hosting an index is the server-side counterpart to How to use private package indexes with uv, which covers the client configuration for managed services like AWS CodeArtifact and JFrog Artifactory.

How to install from a pylock.toml lockfile with pip

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

A teammate hands you a pylock.toml. Or uv’s uv export --format pylock.toml produces one. Now you need pip to install from it. As of pip 26.1 (April 2026), pip install -r pylock.toml works, with a few caveats worth knowing before you put it in CI.

Confirm pip 26.1 or newer

The -r pylock.toml form was added in pip 26.1. Older pips will treat the file as a regular requirements file and choke on the first TOML line.

How to install uv on 32-bit Raspberry Pi OS

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

uv’s standalone installer works on 32-bit Raspberry Pi OS (armv7l), but three quirks bite first-time users: uv python install can fail to detect glibc on some Pi setups, PyPI rarely ships armv7l wheels, and a 32-bit userland running on a 64-bit kernel reports the wrong architecture. This guide walks through each so a 32-bit Pi install ends up in a working state.

For 64-bit Pi OS, the standard path applies; see How to run Python scripts on a Raspberry Pi with uv.

How to migrate from Pipenv to uv

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Pipenv combines pip and virtualenv into a single tool. uv covers the same ground and adds Python version management, a standards-compliant pyproject.toml-based workflow, and significantly faster dependency resolution.

Migrating replaces the Pipfile and Pipfile.lock with pyproject.toml and uv.lock, and swaps pipenv commands for their uv equivalents.

Automated migration

The migrate-to-uv tool automates the conversion.

1. Run the migration tool

$ uvx migrate-to-uv

The tool reads your Pipfile and:

How to migrate from Poetry to uv

Tim Hopper — Thu, 14 May 2026 14:35:17 -0400

This guide walks through the process of migrating a Poetry-managed Python project to uv using the migrate-to-uv tool.

Prerequisites

uv installed
A Poetry-managed Python project

Basic Migration

1. Navigate to your Poetry project directory

cd your-poetry-project

2. Run the migration tool

uvx migrate-to-uv

The tool will:

How to migrate from requirements.txt to pyproject.toml with uv

Tim Hopper — Mon, 04 May 2026 08:09:53 -0400

To migrate a requirements.txt project to pyproject.toml, run uv init --bare to create a minimal pyproject.toml, then uv add -r requirements.txt to import every dependency. uv reads the file, writes the packages into [project.dependencies], and generates a uv.lock file that pins exact resolved versions.

For a detailed explanation of why pyproject.toml replaces requirements.txt, see why choose pyproject.toml over requirements.txt.

Prerequisites

Install uv if it isn’t already on your system.

How to migrate from setup.py to pyproject.toml

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

The setup.py file was long the dominant way to configure a Python package. PEP 621 changed that by standardizing project metadata in pyproject.toml, and every major build backend now supports it. Migrating removes the need for executable configuration files, makes metadata readable by any tool, and aligns a project with current packaging standards.

This guide covers projects that use setuptools as their build backend. If a project uses Poetry, see How to migrate from Poetry to uv.

How to migrate from uv to pip

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Moving a uv-managed project to pip is mostly an audit of pyproject.toml, not a rebuild of the project. uv consolidates Python interpreter installs, virtual environments, resolution, package installation, and lockfile generation into one tool, but if a project’s metadata sticks to packaging standards, most of the substitutes are short. This how-to walks through the audit and the runtime equivalents: pyenv on macOS and Linux, the official python.org installer on Windows.

Audit your pyproject.toml for uv-specific tables

Before exporting a lockfile, scan your pyproject.toml for settings under [tool.uv] and tables under [tool.uv.*]. Anything outside that namespace is already standardized and pip can read it. The settings that matter:

How to Publish Python Packages with Digital Attestations

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Digital attestations let PyPI record who published each file, not just what the file contains. When consumers generate a pylock.toml lockfile, their tools can write your package’s publisher identity into the lockfile. Any change to that identity in a future update becomes visible in code review.

This guide shows how to configure a GitHub Actions workflow that publishes to PyPI with attestations enabled. The setup requires trusted publishing; attestations are cryptographically tied to the same OIDC identity that trusted publishing uses.

How to Publish to PyPI with Trusted Publishing

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Trusted publishing lets GitHub Actions upload packages to PyPI without storing any secrets. Instead of creating an API token and pasting it into your CI settings, you tell PyPI which GitHub repository and workflow are allowed to publish. GitHub Actions then proves its identity to PyPI using an OIDC token that lives only for the duration of the workflow run.

This guide covers GitHub Actions, the most common CI provider for Python projects. PyPI also supports trusted publishing from GitLab CI/CD, Google Cloud, and ActiveState.

How to Publish to TestPyPI with uv

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

PyPI versions are write-once. Upload 0.1.0 with a broken README or a missing dependency, and the only fix is a new version number. TestPyPI is a parallel index wired to the same tooling where the cost of a bad upload is zero. Upload there first and promote to PyPI only after the rehearsal works end to end.

This guide uses uv for the build, upload, and verification steps. The workflow slots into the trusted-publishing setup for CI or runs entirely from a local shell with an API token.

How to require a virtualenv when installing packages with pip?

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

By default, pip allows installing packages into the global Python environment. This can lead to dependency conflicts and break system tools. Configuring pip to require a virtual environment prevents accidental global installs.

Using an environment variable

Set the PIP_REQUIRE_VIRTUALENV environment variable to true in your shell profile (e.g. ~/.bashrc, ~/.zshrc):

export PIP_REQUIRE_VIRTUALENV=true

With this set, running pip install outside a virtual environment produces an error:

How to run Python scripts on a Raspberry Pi with uv

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Running pip install requests on a fresh Raspberry Pi OS Bookworm install prints error: externally-managed-environment and refuses to install anything into the system Python. uv is the cleanest fix on a Pi: install the prebuilt binary, then run scripts inline with inline metadata or inside a project venv that uv manages for you. This guide covers both paths.

It assumes a Pi running 64-bit Raspberry Pi OS. The 32-bit edition has its own quirks; see How to install uv on 32-bit Raspberry Pi OS. If your project needs picamera2, gpiozero, or another apt-installed library, see How to use picamera2 and GPIO with uv on Raspberry Pi.

How to Set Up Documentation for a Python Package with Sphinx or MkDocs

Tim Hopper — Fri, 15 May 2026 21:28:17 -0400

Sphinx and MkDocs are the two documentation generators most Python packages reach for. They cover the same job (turn Markdown or reStructuredText plus your docstrings into a static HTML site) but optimize for different writers. This guide picks one, scaffolds a docs site inside an existing uv project, and gets a build running locally.

Pick Sphinx or MkDocs

Two questions decide it for most projects.

What’s the dominant content type? API reference dominates in libraries like NumPy and Django, where most pages are autogenerated from docstrings. Sphinx was built for that workload and has the older and broader extension ecosystem around API reference work (intersphinx for cross-project links, sphinx-autodoc-typehints for signature rendering). MkDocs with mkdocstrings covers the API case competently, especially for Python-only projects. MkDocs is friendlier when the docs are prose-first and the API reference is one section among many tutorials and how-tos.

How to use picamera2 and GPIO with uv on Raspberry Pi

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

picamera2, libcamera, and gpiozero ship through apt on Raspberry Pi OS, not through PyPI. A clean uv venv cannot import them, and pip install picamera2 inside that venv fails on the missing libcamera module. The workaround is to install the system packages with apt, then build a uv venv against /usr/bin/python3 that inherits the system site-packages. This guide walks through that setup and the constraints it brings.

It assumes uv is already installed on the Pi. If not, start with How to run Python scripts on a Raspberry Pi with uv.

How to use uv to speed up Hatch

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Hatch can use uv as its installer backend instead of pip and virtualenv. This makes environment creation and dependency installation significantly faster without changing the rest of your Hatch workflow.

Note

This guide assumes you already have a Hatch project and uv installed.

How to use uv to speed up PDM

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

PDM has experimental support for using uv as its resolver and installer (available since PDM 2.19.0). This makes dependency resolution and installation significantly faster without changing the rest of your PDM workflow.

Note

How to Verify Dependencies with Hashes in uv

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Dependency hashes let uv verify that every downloaded artifact matches what was resolved, catching tampering before anything gets installed.

Hashes in uv.lock

uv.lock includes SHA-256 hashes for every distribution by default. After running uv lock or uv add, each entry in the lockfile contains hashes for both sdists and wheels:

[[package]]
name = "certifi"
version = "2026.2.25"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "...", hash = "sha256:e887ab5cee78ea814d3472169153c2d12cd43b14bd03329a39a9c6e2e80bfba7" }
wheels = [
    { url = "...", hash = "sha256:027692e4402ad994f1c42e52a4997a9763c646b73e4096e4d5d6db8af1d6f0fa" },
]

When uv sync or uv run installs packages, it checks each downloaded artifact against these hashes. If a hash does not match, installation fails.

How to Vet a Python Package Before Installing It

Tim Hopper — Fri, 15 May 2026 21:28:17 -0400

litellm 1.82.7 and 1.82.8, and Lightning AI 2.6.2 and 2.6.3, hit PyPI before matching source releases appeared on GitHub. A 30-second tag check would have caught either one. Use this five-minute pre-install routine to catch that kind of Python supply chain attack before adding a package to pyproject.toml.

Read the PyPI signals

Open the package page on PyPI and check four things.

Download trend. Run uvx with pypistats to see recent download counts:

How to write install instructions for a Python library

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

A library’s README is the first place a new user lands, and the install command in that README is the first thing they copy. AI coding agents copy it too. If the only command shown is pip install mylib, every uv user has to translate, and every agent learns one more reason to default to pip. Lead with uv, keep pip as the fallback, and the snippet works for everyone.

Lead with `uv add`

Put the uv command first in the install section. Keep pip as a clearly labeled fallback.

Nuitka

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Nuitka is a Python-to-C compiler that translates CPython bytecode into C source, then compiles and links the result against libpython. The output runs without a separate Python installation and can ship as a standalone folder, a self-extracting single-file executable, or an importable extension module. Nuitka runs on Linux, macOS, and Windows; the build machine needs a C toolchain (gcc, clang, or MSVC). Install it with uv tool install nuitka or pipx install nuitka. Nuitka is AGPL-3.0+ with a runtime exception for compiled output, so the license does not carry over to the applications it produces.

PDM: Python Package and Dependency Manager

Tim Hopper — Mon, 27 Apr 2026 09:16:18 -0400

PDM is a Python package and dependency manager that implements the modern PEP 517/518 build-system interface and reads PEP 621 project metadata from pyproject.toml.

When to use PDM

Use PDM when you have an existing project built around its workflow and want a standards-compliant package manager with lockfile support and dependency groups. PDM’s strict adherence to the PEP 517/518 build-system interface and PEP 621 project metadata makes it a good fit for teams that prioritize alignment with official Python packaging standards. For new projects, uv provides faster performance and broader functionality; PDM’s standalone build backend, pdm-backend, can still be used in uv projects without adopting the full PDM CLI.

pip: Python Package Installer

Tim Hopper — Thu, 14 May 2026 14:35:17 -0400

pip is the Python Package Authority’s (PyPA) standard package installer. It enables installing and managing Python packages from the Python Package Index (PyPI) and other package indexes. pip comes with modern Python installations and serves as the default tool for package operations in the Python ecosystem.

While pip remains Python’s default package installer, many workflows benefit from newer tools like uv that provide better performance and more integrated functionality.

Core Functionality

pip provides essential package management capabilities:

pip-tools: Python Dependency Pinning Tools

Tim Hopper — Mon, 04 May 2026 08:09:53 -0400

pip-tools is a set of command-line utilities for managing Python dependency pinning. It consists of two commands: pip-compile for resolving and locking dependencies, and pip-sync for synchronizing a virtual environment to match a lockfile.

Note

pipenv: Python Dependency Manager

Tim Hopper — Sat, 18 Apr 2026 11:22:55 -0400

pipenv is a tool for managing application dependencies analogous to npm for Node.js or bundler for Ruby.

Per the pipenv documentation:

Pipenv automatically creates and manages a virtualenv for your projects, as well as adds/removes packages from your Pipfile as you install/uninstall packages. It also generates a project Pipfile.lock, which is used to produce deterministic builds.

When to Use Pipenv

Pipenv fits teams already committed to a Pipfile-based workflow for an application project, where the existing lockfile and automatic virtualenv still cover the team’s needs. Its release cadence has slowed relative to newer tools, and it predates the pyproject.toml standards the rest of the packaging ecosystem has adopted.

Pipfile: Python Dependency Declaration Format

Tim Hopper — Mon, 04 May 2026 08:09:53 -0400

A Pipfile is a TOML-formatted file that declares a project’s Python dependencies for use with Pipenv. It was originally proposed as a successor to requirements.txt, adding structured runtime and development dependency sections alongside a paired Pipfile.lock for reproducible installs.

The standalone pipfile specification project at pypa/pipfile has not seen substantive activity since 2019. The format lives on inside Pipenv, which reads and writes both the Pipfile and Pipfile.lock. The broader Python packaging ecosystem moved toward dependency declarations in pyproject.toml under PEP 621, and the two formats are no longer in active competition.

Poetry: Python Packaging and Dependency Manager

Tim Hopper — Thu, 23 Apr 2026 06:56:42 -0400

Poetry is a Python packaging and dependency management tool that handles dependency installation, virtual environment management, package building, and publishing. It aims to provide a unified workflow for Python project management through configuration in pyproject.toml.

When to Use Poetry

Poetry fits teams that already have an established Poetry workflow and need integrated dependency management, virtual environment handling, and package publishing. Its lockfile and dependency group features suit application projects that require reproducible builds.

Publishing Your First Python Package to PyPI

Tim Hopper — Tue, 28 Apr 2026 08:41:30 -0400

This tutorial guides you through publishing a Python package to the Python Package Index (PyPI) using uv. You’ll learn the essential steps of building and uploading a package that others can install with pip or uv.

Since this is your first package, we’ll start by uploading to TestPyPI, a “separate instance of the Python Package Index that allows you to try distribution tools and processes without affecting the real index.”

Prerequisites

uv installed (installation guide)
A TestPyPI account (register here)
A Python project ready for distribution

Setting Up Your Project

Create a new project with a name that is not currently taken on Test PyPI. You might try something like your name followed by a random number, e.g. timhopper2456543. Browse the project’s URL at https://test.pypi.org/project/<PACKAGE_NAME>/ first; if it returns a project page rather than a 404, the name is taken and uv publish will fail later.

Python Developer Tooling Handbook – Packaging

Why Doesn't the Authoritative Python Packaging Guide Mention the Best Thing that's Happened to Python Packaging?

What uv Does

Briefcase

build: Python Package Build Frontend

Core Functionality

Build Operations

Command Interface

Technical Design

Build a Python library with a C extension

Prerequisites

Build a Python library with a C++ extension

Prerequisites

Build a Python library with a Rust extension

Prerequisites

cibuildwheel: Cross-Platform Python Wheel Builder

Conda Package

Package Formats

cx_Freeze

When to Use cx_Freeze

distutils: Python's Original Build System

What It Did

Does Poetry Support Python Standards for Dependency Management?

Related Handbook Pages

Learn More

Flit: Python Package Build and Publish Tool

Hatch: Python Project Manager

When to Use Hatch

How do I ship a Python application to end users?

How do uv and Poetry compare?

Scope

How Python Package Formats Evolved: From tar.gz to .whl

How to add dynamic versioning to uv projects

Prerequisites

Configure the build system

How to Build Multi-Platform Wheels with cibuildwheel

Prerequisites

Configure cibuildwheel

How to convert a script with requirements.txt to PEP 723 inline metadata

Translate the requirements.txt into inline metadata

How to Create and Distribute a Python CLI Tool

How to fix the "externally-managed-environment" error

Installing project dependencies

How to format pyproject.toml with taplo

Format with uvx

How to Host Your Own Python Package Index

How to install from a pylock.toml lockfile with pip

Confirm pip 26.1 or newer

How to install uv on 32-bit Raspberry Pi OS

How to migrate from Pipenv to uv

Automated migration

1. Run the migration tool

How to migrate from Poetry to uv

Prerequisites

Basic Migration

1. Navigate to your Poetry project directory

2. Run the migration tool

How to migrate from requirements.txt to pyproject.toml with uv

Prerequisites

How to migrate from setup.py to pyproject.toml

How to migrate from uv to pip

Audit your pyproject.toml for uv-specific tables

How to Publish Python Packages with Digital Attestations

How to Publish to PyPI with Trusted Publishing

How to Publish to TestPyPI with uv

How to require a virtualenv when installing packages with pip?

Using an environment variable

How to run Python scripts on a Raspberry Pi with uv

How to Set Up Documentation for a Python Package with Sphinx or MkDocs

Pick Sphinx or MkDocs

How to use picamera2 and GPIO with uv on Raspberry Pi

How to use uv to speed up Hatch

How to use uv to speed up PDM

How to Verify Dependencies with Hashes in uv

Hashes in uv.lock

How to Vet a Python Package Before Installing It

Read the PyPI signals

How to write install instructions for a Python library

Lead with uv add

Nuitka

Lead with `uv add`