distro

distro is the community-maintained replacement for Python’s platform.linux_distribution() function, which was deprecated in Python 3.5 and removed entirely in Python 3.8. It reliably detects the Linux/BSD distribution a program is running on — reading /etc/os-release, LSB release data, and distro-specific release files — and exposes machine-readable IDs, version strings, and human-readable names through a small Python API.

With over 90 million weekly downloads, distro has become a near-ubiquitous transitive dependency, pulled in by pip, OpenAI’s Python SDK, and countless other tools that need to branch behavior based on the host Linux distribution (e.g. choosing a package manager, picking a prebuilt binary, or tailoring installation instructions).

What You Get

• distro.id(), distro.version(), distro.name() and related functions for distro identification
• A LinuxDistribution class for advanced use cases needing custom release-file paths
• A command-line interface (python -m distro) that prints detected distro info as JSON
• Consistent parsing across os-release, LSB release, and legacy distro-specific release files
• Zero required runtime dependencies beyond the Python standard library

Common Use Cases

• Package managers and installers (like pip) selecting distro-appropriate binary wheels or repositories
• CLI tools tailoring setup instructions or error messages to the user’s specific Linux distribution
• SDKs (such as OpenAI’s Python client) including distro/OS metadata in request telemetry or user-agent strings
• System administration scripts branching logic based on whether they’re running on Debian, Fedora, Alpine, etc.

Under The Hood

Architecture: The library is essentially one module, src/distro/distro.py (~1,500 lines), centered on a LinuxDistribution class that tries multiple detection strategies in priority order: parsing /etc/os-release (the modern systemd standard), falling back to lsb_release command output, and finally checking a table of legacy distro-specific release files (e.g. /etc/redhat-release, /etc/debian_version). Module-level convenience functions (id(), version(), name(), etc.) wrap a lazily-instantiated singleton of this class for the common case, while __main__.py exposes the same data through a CLI entry point.

Tech Stack: Pure Python standard library — no runtime dependencies at all — using argparse for the CLI, subprocess to shell out to lsb_release when needed, and re/shlex for parsing release-file formats. Packaging uses a standard pyproject.toml with setuptools as the build backend, targeting broad Python version compatibility given its role as a near-universal transitive dependency.

Code Quality: tests/test_distro.py exercises detection logic against a tests/resources/ fixture directory of real-world os-release/lsb_release samples from dozens of actual distributions, which is an effective strategy for a library whose whole job is correctly parsing heterogeneous real-world file formats. The module is fully type-hinted and includes deprecation warnings for older function names, showing deliberate API stewardship across the multi-year life of the project.

API Design: The public API deliberately mirrors the shape of the removed platform.linux_distribution() tuple/function pattern to minimize migration friction for existing codebases, while module-level functions like distro.id() require zero setup — no client construction, no configuration object — making it essentially frictionless to adopt as a dependency, which likely explains its near-ubiquitous presence as a transitive dependency across the Python packaging ecosystem.