pip-wheel

Build a wheel for a package

$ pip wheel [package]

$ pip wheel [[-r|--requirement]] [path/to/requirements.txt]

$ pip wheel [package] [[-w|--wheel-dir]] [path/to/directory]

$ pip wheel [package] --no-deps

$ pip wheel [path/to/project]

$ pip wheel git+[https://github.com/user/repo.git]

pip wheel [options] <package/requirement specifier> ...
pip wheel [options] -r <requirements file> ...
pip wheel [options] <directory>

--wheel-dir <dir>, -w <dir>
    Directory to store built wheels. Defaults to the current directory.

--no-deps
    Don't build or download package dependencies. Only build the specified packages.

--no-binary <package>
    Do not use pre-built binary packages (wheels) for the specified package(s). Force building from source.

--only-binary <package>
    Only use pre-built binary packages (wheels) for the specified package(s). Do not build from source.

-r <file>, --requirement <file>
    Build wheels for packages listed in the given requirements file.

-f <url>, --find-links <url>
    Look for project archives in this URL or path. Can be an HTML file or a directory containing packages.

--index-url <url>, -i <url>
    Base URL of the Python Package Index (e.g., https://pypi.org/simple).

--extra-index-url <url>
    Extra URLs of package indexes to use in addition to the primary index URL.

--build-option <option>
    Extra option to pass to setup.py bdist_wheel for controlling the build process.

--no-build-isolation
    Disable isolation when building a modern source distribution. Uses the current environment for dependencies.

--python-version <version>
    The Python version to use for wheel building (e.g., '3' or '3.8').

--platform <platform>
    Specific platform to build wheels for (e.g., 'manylinux1_x86_64', 'win_amd64').

--abi <abi>
    Specific ABI (Application Binary Interface) to build wheels for (e.g., 'cp37m').

--implementation <implementation>
    Python implementation to build wheels for (e.g., 'cp' for CPython, 'pp' for PyPy).

pip wheel is a pip subcommand used to build "wheel" files (.whl) from specified Python packages. Wheels are a standard built-package format for Python, designed to allow for easy and fast installation without needing to re-run setup scripts or compilers. This is especially beneficial in environments lacking build tools or internet access during deployment.

The command resolves package dependencies, downloads source distributions if necessary, builds them into wheel files, and stores these files locally. It's a crucial tool for creating a "wheelhouse" – a local directory of pre-built packages – which is invaluable for air-gapped systems, continuous integration/delivery pipelines (CI/CD), and faster, more reliable deployments by avoiding repeated compilation.

• Dependency Handling: By default, pip wheel will download and build dependencies, but it does NOT install them into the current environment. It only places their wheels in the specified wheel directory.
• Platform Specificity: Wheels containing compiled extensions are platform-specific. A wheel built on Linux will typically not work on Windows or macOS. Pure-Python wheels are generally cross-platform.
• Build Tools Required: If a package contains compiled extensions (e.g., C, C++, Fortran), the system where pip wheel is run must have the necessary build tools (like a C compiler, Python development headers) installed.

pip wheel is commonly used to create a 'wheelhouse' – a local directory containing pre-built .whl files for a project and all its dependencies. This wheelhouse can then be used to install packages rapidly and offline, typically with a command like:
pip install --no-index --find-links /path/to/wheelhouse -r requirements.txt.
This approach guarantees reproducible builds and simplifies deployments to air-gapped or production environments.

The filename of a wheel (e.g., numpy-1.21.2-cp39-cp39-manylinux_2_17_x86_64.whl) contains 'tags' that describe its compatibility. These tags specify the Python version, ABI, and platform it was built for. When building wheels for different deployment targets, it's crucial to consider these tags and potentially build separate wheelhouses for each unique environment (e.g., different Python versions or operating systems) using options like --python-version and --platform.

The wheel format (.whl), formally introduced as PEP 427 in 2012, aimed to standardize a built-package format for Python that would be faster and more reliable to install than traditional source distributions (sdist). pip adopted the wheel subcommand to simplify the creation of these binary packages. This made it significantly easier for developers to pre-build their project's dependencies for various deployment scenarios, particularly in CI/CD pipelines and environments with restricted internet access. Wheels have since become the preferred method for distributing and installing most Python packages, especially those with compiled components.

pip install(1), pip download(1), pip install --no-index --find-links(1)