Python Developer Tooling Handbook – Python Developer Tools Reference

Anaconda: Python and R Data Science Platform

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

Anaconda Distribution is a pre-packaged Python and R data science platform maintained by Anaconda, Inc. It bundles the conda package manager, a Python interpreter, and over 1,500 scientific computing libraries into a single installer. The current release, Anaconda Distribution 2025.12, ships with Python 3.13.9 and conda 25.11.0.

Warning

Basedpyright: Python Type Checker (pyright Fork)

Tim Hopper — Fri, 08 May 2026 03:19:33 -0400

Basedpyright is a static type checker and language server for Python, maintained by DetachHead as a community fork of Microsoft’s pyright. It tracks upstream pyright closely and adds diagnostic rules, stricter defaults, and language-server features that Microsoft keeps exclusive to its closed-source Pylance extension.

The fork exists because pyright ships as an npm package and depends on Node.js, which makes it awkward to pin as a project dependency, and because the editor features most Python developers associate with “pyright” actually live in Pylance, whose license restricts it to official Microsoft VS Code builds. Basedpyright packages the language server on PyPI so uv add --dev basedpyright works, and re-implements Pylance-style features (inlay hints, semantic highlighting, docstring completion) in the open-source server so VS Code forks like Cursor, VSCodium, and Positron can use them.

Black: Python Code Formatter

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

Black is an opinionated Python code formatter that automatically formats Python code to conform to a strict subset of PEP 8. Black deliberately offers minimal configuration options, aiming to end arguments about code formatting by providing “one way” to format code.

Consider using Ruff instead of Black. Ruff provides the same formatting capabilities but with significantly better performance. Ruff also includes linting, import sorting, and other code quality tools in a single high-performance package.

When to use Black

Black suits codebases that already run it in CI or pre-commit hooks and teams that want a zero-config formatter to end style debates. It has been the default Python formatter for years, with stable output that editor plugins, pre-commit hooks, and CI configurations across the ecosystem rely on.

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:

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

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

Conda is a language-agnostic, cross-platform package and environment manager. Where pip installs Python packages from PyPI, conda resolves dependencies across Python, R, C/C++, Fortran, and other languages in a single dependency graph. The current stable release is 26.3.1 (March 2026).

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.

conda-forge: Community Conda Package Channel

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

conda-forge is a community-maintained collection of conda packages distributed through a public channel on anaconda.org. Over 25,000 feedstocks (package repositories) produce builds for Linux, macOS, and Windows across multiple CPU architectures. Each feedstock contains a build recipe in its own GitHub repository, and automated infrastructure rebuilds packages when dependencies change or new platforms appear.

Note

Cookiecutter: Python Project Template Tool

Tim Hopper — Mon, 04 May 2026 08:02:03 -0400

Cookiecutter is a cross-platform command-line utility that creates projects from templates. It generates project structures by copying template directories and replacing templated variables with user-provided values, supporting any programming language or markup format.

Core Functionality

Template Processing

Copies source directory trees and replaces names surrounded by templating tags {{ }} with values from cookiecutter.json
Supports variable replacement in file names, directory names, and file contents
Uses Jinja2 templating engine for advanced variable processing
Handles multiple data types including strings, lists, booleans, and dictionaries

Interactive Configuration

Command-line prompts for template variables
Default values specified in cookiecutter.json
User can accept defaults or provide custom values during project generation
Support for conditional prompts and validation

Additional Features

Hooks System

Pre-generation hooks for input validation and setup tasks
Post-generation hooks for environment initialization, dependency installation, and git repository setup
Access to template variables within hook scripts

Advanced Templating

Private variables for computed values
Choice variables for predefined options
Template inheritance for shared configurations
Custom Jinja2 extensions and filters

Installation and Usage

Installation

Install Cookiecutter as a global CLI tool with uv:

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.

direnv: Per-Directory Environment Variables for Python

Tim Hopper — Thu, 30 Apr 2026 07:12:25 -0400

direnv is a shell extension that loads and unloads environment variables based on the current working directory. It reads a per-directory .envrc file when entering a folder and reverts the environment when leaving. Although direnv is language-agnostic, it is widely used in Python projects to activate virtual environments and export project-specific settings without polluting the global shell.

Key Features

Loads variables from .envrc on cd into a directory and unloads them on cd out
Provides a stdlib of layout helpers, including layout python, layout python3, layout pyenv, and layout pipenv
Supports bash, zsh, fish, tcsh, elvish, and PowerShell
Requires explicit per-directory authorization with direnv allow before any new .envrc runs

Installation

direnv is distributed through most package managers:

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.

flake8: Python Linter

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

Flake8 has been largely superseded by newer tools like Ruff, which offer significantly faster performance and more features. Consider using Ruff for new projects.

Flake8 is a Python linting tool that enforces style consistency and checks for programming errors. It combines multiple code quality tools into a single interface: PyFlakes for logical errors, pycodestyle for style checking, and mccabe for code complexity checking.

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.

Furo: Sphinx Documentation Theme

Tim Hopper — Wed, 29 Apr 2026 14:33:02 -0400

Furo is a Sphinx theme written by Pradyun Gedam. It is a clean, customisable replacement for Sphinx’s default alabaster theme, with built-in light and dark modes, a responsive layout, and a focused sidebar.

Note

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.

Homebrew: macOS Package Manager for Python

Tim Hopper — Mon, 04 May 2026 08:02:03 -0400

Homebrew is a package manager for macOS and Linux that makes installing software packages simple. While not Python-specific, it provides an important way to install Python tools and dependencies on macOS systems.

Core Capabilities

Installs packages (“formulae”) and larger binary packages (“casks”)
Manages package dependencies
Updates installed packages
Installation and uninstallation using brew install and brew uninstall
Installs Python interpreters (brew install python)
Installs Python tools like uv and pipx
Provides dependency libraries needed for Python packages (e.g. openssl, sqlite)

While Homebrew can install Python, it’s not recommended as your primary way to manage Python versions for development projects. Homebrew updates can unexpectedly change Python versions, breaking your project environments. Instead, use dedicated Python version management tools like uv python install or pyenv which provide more reliable and granular control over Python versions. See Should I use Homebrew to install Python? for the full reasoning.

Pros

Simple to use with consistent commands
Well-maintained and stable
Large collection of available packages

Cons

macOS/Linux only (no Windows support)
Can conflict with system Python on macOS
Updates may break existing Python setups
Less granular control compared to Python-specific tools

Learn More

Homebrew Documentation
Homebrew and Python
Formula Repository
Should I use Homebrew to install Python? explains why Homebrew’s Python is for Homebrew’s own packages, not your projects.
Why should I avoid system Python? covers the broader risk of using interpreters managed by another package manager.
How to install uv on macOS walks through the recommended replacement for brew install python.

IPython: Enhanced Python Interactive Shell

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

IPython is an enhanced interactive Python interpreter that provides a powerful command-line interface with advanced features like syntax highlighting, tab completion, magic commands, and rich display capabilities. It serves as the computational kernel for Jupyter notebooks.

Core Features

Enhanced Interactive Shell

Syntax Highlighting: Real-time code coloring for better readability
Tab Completion: Intelligent autocompletion for objects, methods, and file paths
History Management: Persistent command history with search capabilities
Rich Output: Native display of images, plots, and formatted data structures
Object Introspection: Detailed information about objects using ? and ??

Magic Commands

IPython provides magic commands prefixed with % for single-line operations or %% for cell-wide operations:

marimo: Reactive Python Notebook

Tim Hopper — Sat, 02 May 2026 08:49:34 -0400

marimo is an open-source Python notebook in which cells re-execute automatically when the variables they read change. Notebooks are stored as plain .py files rather than JSON and are parsed by static analysis to derive a deterministic execution order. The same file can be run as a standalone script or inside a sandboxed environment managed by uv. It is licensed under Apache-2.0 and requires Python 3.10 or newer.

Reactive Notebook Model

The traditional notebook model decouples cell ordering from execution. A Jupyter cell runs only when the user runs it, so the in-memory kernel state can drift from the visible code. Variables outlive the cells that defined them, and re-running cells out of order produces results that a fresh kernel restart cannot reproduce. This is the hidden state problem.

Material for MkDocs: Documentation Theme and Framework

Tim Hopper — Wed, 29 Apr 2026 14:33:02 -0400

Material for MkDocs is a theme and feature framework for MkDocs. Built by Martin Donath (squidfunk), it layers Material Design styling, client-side search, dark mode, code annotations, and a wide configuration surface on top of the base MkDocs build pipeline.

Note

MkDocs: Markdown Documentation for Python Projects

Tim Hopper — Fri, 01 May 2026 06:58:04 -0400

MkDocs is a static site generator that builds documentation websites from Markdown source files. A project’s structure, navigation, theme, and plugins are declared in a single mkdocs.yml file at the repo root.

Note

mkdocstrings: Autogenerate API Documentation in MkDocs

Tim Hopper — Wed, 29 Apr 2026 14:33:02 -0400

mkdocstrings is a MkDocs plugin that generates API documentation from source code and injects it directly into Markdown pages. The base plugin is language-agnostic; concrete language support ships as separate handler packages.

Note

mypy: Python Static Type Checker

Tim Hopper — Tue, 05 May 2026 06:57:20 -0400

mypy is a static type checker for Python that analyzes type annotations to detect bugs before runtime. It has been the default Python type checker since 2012 and has the broadest ecosystem support of any Python type checking tool.

When to use mypy

Use mypy when you want to catch type-related bugs before runtime by adding static type checking to a Python project. It is the most established Python type checker with broad ecosystem support, making it a reliable default for projects that are adopting type annotations incrementally. For faster checking or tighter VS Code integration, consider pyright; for an emerging alternative from the creators of Ruff, see ty.

nox: Python Test Automation Tool

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

nox manages Python virtual environments and runs tests across multiple Python versions and configurations. Unlike tox, which uses INI format configuration files, nox uses Python files for configuration, providing more flexibility and control. Hatch offers a third approach with its environment matrix system configured in pyproject.toml.

When to Use nox

nox solves the problem of running test suites, linters, and other checks across multiple Python versions and dependency combinations. Choose nox over tox when test automation logic requires conditionals, loops, or dynamic session generation that INI configuration cannot express. Projects with straightforward multi-version testing may find uv’s built-in multi-version support sufficient without a separate tool; see Do you still need tox or nox with uv? for guidance.

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.

pdb: Python's Built-in Debugger

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

pdb is Python’s interactive source debugger, distributed as a module in the standard library. It supports setting breakpoints, single-stepping at the source-line level, inspecting and modifying variables in any stack frame, and post-mortem analysis of an unhandled exception. The interface is line-oriented and runs in any terminal with no external dependencies.

When to use pdb

Use pdb when a problem can be reproduced locally and adding a print statement is not enough. Drop a breakpoint() call at the line of interest, run the program, and inspect state interactively. For a crash that has already happened, run the script with python -m pdb -c continue script.py to land in post-mortem at the offending frame. pdb pauses the entire process, so it is not appropriate for debugging long-running production services; reach for logging or a sampling profiler instead.

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 — Mon, 27 Apr 2026 21:44:29 -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.

pipx: Install Python CLI Tools in Isolation

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

pipx is a command line tool to install and run Python command line applications in isolated environments. Each installed application gets its own virtual environment, preventing dependency conflicts between tools while making their executables available on your PATH.

When to use pipx

Reach for pipx when installing standalone Python CLI tools (ruff, csvkit, httpie, cookiecutter) that should stay isolated from any project’s virtual environment and remain on PATH across shell sessions. It fits teams that already have pipx wired into setup scripts, documentation, or CI and prefer a narrowly-scoped tool over a general-purpose one. For new installations, uv provides equivalent isolation through uv tool install and uvx while also handling Python version and project management in the same binary.

Pixi: Multi-Language Package and Workflow Manager

Tim Hopper — Sat, 25 Apr 2026 06:42:19 -0400

Pixi is a cross-platform package manager and workflow tool that manages both conda-forge packages and PyPI packages from a single project manifest. It replaces conda’s global environment model with project-local environments and automatic lock files.

Note

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.

prek: Fast Pre-commit Hook Runner for Python

Tim Hopper — Sun, 19 Apr 2026 07:03:22 -0400

prek is a fast reimplementation of the pre-commit framework that serves as a faster, dependency-free, drop-in alternative. It maintains full compatibility with existing .pre-commit-config.yaml files while providing significant performance improvements, reduced disk usage, and an enhanced CLI experience.

Key Features

Performance

prek executes multiple times faster than the original pre-commit tool while using approximately half the disk space. It achieves this through shared toolchain management across hooks, parallel repository cloning and hook installation, and concurrent hook execution based on priority levels.

profiling.sampling: Statistical Profiler in the Standard Library

Tim Hopper — Thu, 07 May 2026 13:56:14 -0400

profiling.sampling is the statistical sampling profiler that ships with Python 3.15, developed under the codename Tachyon. It samples the call stacks of a Python process on a timer rather than instrumenting every call, and it can attach to a process that is already running by PID. The CLI is invoked as python -m profiling.sampling, with run and attach as the two profiling entry points, dump for a single stack snapshot, and replay for converting saved binary profiles to other output formats.

py-spy: Sampling Profiler for Python

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

py-spy is a sampling profiler for Python programs. It visualizes where a Python process spends its time without restarting the process or modifying its code. py-spy runs in a separate process from the program it profiles and reads stack information out of the target’s memory, which keeps overhead low enough that the project documents it as safe to use against production workloads.

When to Use py-spy

Use py-spy when a Python process is already running and needs to be profiled in place: a web worker under load, a data-pipeline job mid-run, a stuck process that needs a stack dump, or any CPU-bound script whose profile should not be distorted by per-function tracing overhead. py-spy is a practical default for production CPU profiling because it requires no instrumentation and can be attached and detached at will. For line-by-line attribution inside a known hot function, reach for line_profiler; for memory rather than CPU, reach for memray.

pyenv: Python Version Manager

Tim Hopper — Tue, 05 May 2026 06:54:22 -0400

pyenv is a command-line tool for installing, managing, and switching between multiple Python interpreter versions on macOS and Linux. It intercepts Python commands through shell shims, routing them to whichever interpreter version is active for the current directory, user, or system.

When to use pyenv

pyenv fits workflows where Python version management should remain separate from package management. It pairs with pip, venv, or any other packaging tool without imposing opinions on how dependencies are managed. If you want a single tool that also handles dependencies and virtual environments, uv covers version management alongside those workflows.

pyenv-virtualenv: Python Virtual Environment Plugin

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

pyenv-virtualenv is a plugin for pyenv that creates and manages virtual environments tied to specific Python versions. It extends pyenv with a pyenv virtualenv command and hooks into shell initialization so the right environment activates whenever a directory’s .python-version file names it.

When to use pyenv-virtualenv

pyenv-virtualenv fits teams already running pyenv who want directory-scoped virtual environments without changing version managers. The plugin pairs with pip or any other installer because it only handles environment creation and activation. Teams looking for a single tool that combines Python version management, virtual environments, lockfiles, and dependency resolution may prefer uv. For pyenv users moving to uv, see How to switch from pyenv to uv for managing Python versions.

PyInstaller

Tim Hopper — Wed, 22 Apr 2026 06:46:02 -0400

PyInstaller is a Python application bundler that freezes a Python program, the CPython interpreter it was built against, and every imported dependency into a single distributable. The output runs on end-user machines without a pre-installed Python interpreter and without a virtual environment. PyInstaller supports CPython on macOS, Linux, and Windows; there is no iOS, Android, or tvOS target. Install it with uv tool install pyinstaller or pipx install pyinstaller.

Key Features

One-folder bundles via --onedir and self-extracting single-file executables via --onefile
Hook system that declares hidden imports, data files, and runtime patches for third-party packages
Community hook repository (pyinstaller-hooks-contrib) installed alongside PyInstaller, covering packages such as NumPy, SciPy, PyQt, and Matplotlib
Spec file workflow for declarative builds (pyinstaller my.spec) in addition to CLI flags
--exclude-module flag for trimming unused transitive dependencies out of a bundle
Optional UPX compression for smaller executables

Build Process

A PyInstaller spec file orchestrates four stages: Analysis walks the entry-point script’s imports to produce a dependency graph and applies hooks for packages that need special handling. PYZ compiles pure-Python modules to bytecode and packs them into a ZlibArchive. EXE concatenates the PYZ, extension modules, shared libraries, and data files (wrapped internally in a PKG CArchive) onto a precompiled native bootloader and writes the executable. COLLECT copies the executable plus any external dependencies into the output folder for one-folder builds; one-file builds skip COLLECT and emit the self-extracting executable directly.

pylint: Python Static Code Analyzer

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

pylint is a static code analysis tool that identifies programming errors, coding standard violations, and potential bugs in Python code. It analyzes source code without running it to find issues from basic syntax errors to complex design problems.

When to use pylint

Pylint fits codebases that depend on its semantic checks, such as cyclomatic complexity, duplicate-code detection, and design-rule enforcement that go beyond what style-focused linters catch. Teams with an established .pylintrc and CI pipelines tuned around its output keep a familiar tool backed by a long-running plugin ecosystem.

pyproject.toml: The Standard Python Project Configuration File

Tim Hopper — Fri, 08 May 2026 03:19:33 -0400

pyproject.toml is the standard configuration file for a Python project. It is written in TOML and lives in the project root. A single file captures three kinds of information that older Python projects scattered across setup.py, setup.cfg, MANIFEST.in, requirements.txt, .flake8, mypy.ini, pytest.ini, and tox.ini: project metadata, build-system requirements, and third-party tool configuration.

PEP 518 introduced pyproject.toml in 2016 to declare build-system requirements in a tool-agnostic way. PEP 621 extended it in 2020 with a standardized [project] table for project metadata. Together, the two PEPs make pyproject.toml the canonical home for a Python project’s configuration.

Pyrefly: Python Type Checker by Meta

Tim Hopper — Fri, 08 May 2026 03:19:33 -0400

Pyrefly is a static type checker and language server for Python, developed by Meta. It performs static analysis on Python code to identify type-related issues before runtime and provides IDE features like code navigation, autocompletion, and semantic highlighting.

Pyrefly is a clean-slate implementation inspired by Meta’s earlier Pyre type checker. It uses a new type inference engine, a custom incremental computation model, and multi-threaded parallel checking.

When to use Pyrefly

Pyrefly is worth evaluating for large Python codebases where mypy or pyright feel slow and where aggressive type inference that catches errors in unannotated code is desirable. Its conformance score (90% of the typing spec test suite as of April 2026, per the Python typing conformance dashboard) is higher than mypy and ty, though lower than pyright and Zuban (another Rust-based checker).

pyright: Python Static Type Checker by Microsoft

Tim Hopper — Fri, 08 May 2026 03:19:33 -0400

pyright is a static type checker and language server for Python, built and maintained by Microsoft. It analyzes type annotations to detect bugs before runtime and provides editor features like autocompletion, hover information, and go-to-definition.

pyright powers the Pylance extension for Visual Studio Code. Pylance is closed-source and adds features on top of pyright’s open-source language server, but pyright itself can be used with any editor that supports LSP.

When to use pyright

pyright is a strong choice for teams that want real-time type feedback in their editor, especially in VS Code through the Pylance extension. Its aggressive type inference catches bugs in unannotated code that mypy would skip by default.

pytest: Python Testing Framework

Tim Hopper — Tue, 21 Apr 2026 11:05:10 -0400

pytest is a mature, feature-rich testing framework for Python that simplifies test writing and execution through a clear, concise syntax. Unlike Python’s built-in unittest module, pytest minimizes boilerplate and offers powerful fixture capabilities, parameterized testing, and a comprehensive plugin ecosystem.

pytest is the standard choice for most Python testing, from small scripts to large applications. Its assert-based syntax requires less code than unittest, and its fixture system scales well as projects grow. The main reasons to prefer unittest over pytest are maintaining a codebase already committed to unittest conventions or working in an environment where third-party packages are restricted.

Python Packaging User Guide

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

The Python Packaging User Guide (PyPUG) is the official guide for packaging, publishing, and installing Python projects using the tools provided by the Python Packaging Authority.

The guide documents:

PyPA-maintained tools (pip, setuptools, wheel, virtualenv, etc.)
Official Python packaging standards and specifications
Core workflows using standard tooling
Package index (PyPI) interaction

While comprehensive for PyPA tools, the guide does not:

Cover all available Python packaging tools
Require tools to follow its guidance
Restrict innovation in packaging approaches
Represent the only valid packaging methods

requirements.txt: Python Dependency File Format

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

A plain-text file format for declaring Python package dependencies. Each line specifies a package and optional version constraint. The file is consumed by pip, uv, and other installers, typically via pip install -r requirements.txt. The filename is a convention, not a requirement — any text file works.

Note

Ruff: Python Linter and Formatter

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

Ruff is a fast Python linter and code formatter from Astral (the makers of uv and ty). It replaces multiple Python code quality tools (like flake8, Black, isort, and pyupgrade) with a single binary.

Ruff includes over 1,000 built-in lint rules and can replace functionality from more than 20 different Python code quality tools.

When to use Ruff

Use Ruff when you want a single, fast tool for linting and formatting Python code instead of maintaining separate configurations for flake8, Black, isort, and other code quality tools. It is a strong default for any Python project, from small scripts to large monorepos, because it handles linting, formatting, and import sorting in one pass with minimal configuration. If you need deeper static analysis beyond what lint rules provide, pair Ruff with a type checker like mypy or pyright; for a comparison with traditional linting, see How do Ruff and Pylint compare?.

sdist: Python Source Distribution Format

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

An sdist (source distribution) is a compressed archive containing the source code, metadata, and build instructions for a Python package. It is one of two standard distribution formats on PyPI, the other being wheel.

What an sdist Contains

An sdist is a .tar.gz archive. Its contents include:

The package’s Python source code
A PKG-INFO file with package metadata (name, version, author, license, etc.)
A pyproject.toml specifying the build backend
Any non-Python files the build backend includes (C extensions, data files, templates)

The format is defined by the source distribution specification, which standardized the layout so that any compliant build frontend can process it.