---
id: wheel-filename
version: "2.1.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# wheel-filename — Parse wheel filenames

License: permissive · Maintenance: active · Downloads: 587.2K/mo

## What it is and what it does

wheel-filename is a lightweight parser for the standardized wheel binary distribution filename format. It takes a wheel filename (as a string, bytes, or path-like object) and parses it into its component parts: project name, version, optional build tag, and the three compatibility tag lists (Python, ABI, and platform). The parser adheres strictly to PEP 427 with minor exceptions: version components are not validated for PEP 440 compliance, and the .whl extension is matched case-insensitively.

The package provides both a Python API via the WheelFilename dataclass and a command-line tool. The dataclass offers methods to extract individual fields, compute build tag tuples for sorting, and generate all simple tag triples from the compatibility tags. It raises ParseError (a ValueError subclass) for invalid filenames. The CLI outputs parsed components as JSON, making it useful in build pipelines and packaging workflows.

Use it for:

- Validate wheel filenames in a package repository or build system before processing.
- Extract compatibility tags to determine which Python versions and platforms a wheel supports.
- Parse wheel metadata in dependency resolution or package compatibility checking tools.
- Automate wheel filename generation or validation in CI/CD pipelines.
- Sort wheels by build tag in package management or distribution workflows.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Parse and validate wheel filenames according to PEP 427, extracting project name, version, build tag, and compatibility tags into structured fields.

Yes. This is a focused, well-maintained utility with no dependencies, permissive licensing, and active development. Install it if you work with wheel files, need to validate filenames, or extract compatibility metadata in packaging tools or build systems.

## Install

pip install wheel-filename
uv add wheel-filename
poetry add wheel-filename

## Installing wheel-filename

Before you install: Low friction: pure Python, no runtime dependencies, and actively maintained with recent releases. Requires Python 3.10 or higher.

License in practice: MIT license permits unrestricted use, modification, and distribution with minimal obligations.

Quickstart:

from wheel_filename import WheelFilename

pwf = WheelFilename.parse('pip-18.0-py2.py3-none-any.whl')
print(pwf.project, pwf.version, pwf.python_tags)

Requires Python 3.10 or higher.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 587.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

wheel filename parsing, pep 427 wheel validation, extract wheel metadata, parse wheel tags, wheel compatibility tags, packaging, wheel-format

[View on SkillFed](https://skillfed.io/packages/wheel-filename) · [View on PyPI](https://pypi.org/project/wheel-filename/)