pip-download

Download Python packages without installing

TLDR

Download a package wheel or source archive to the current directory

$ pip download [package]

Download a specific version of a package

$ pip download [package]==[version]

Download a package and its dependencies to a specific directory

$ pip download [package] [[-d|--dest]] [path/to/directory]

Download a package for a specific platform and Python version

$ pip download [package] --only-binary :all: --platform [platform] --python-version [version]

Download a package from a specific index URL

$ pip download [package] [[-i|--index-url]] [url]

SYNOPSIS

pip download [options] ...
pip download [options] -r

, --dest
    Download packages into the specified . Defaults to the current working directory.

--no-deps
    Do not download package dependencies; only download the specified top-level package(s).

-r , --requirement
    Download all packages listed in the given requirements file. Each line in the file should specify a package.

--platform
    Only download wheels compatible with the specified platform (e.g., linux_x86_64, win_amd64). Use with --python-version for cross-platform downloads.

--python-version
    Only download wheels compatible with the specified Python version (e.g., 3.8, 27). Can be specified multiple times.

--implementation
    Only download wheels compatible with the specified Python implementation (e.g., cp for CPython, pp for PyPy). Can be specified multiple times.

--abi
    Only download wheels compatible with the specified ABI (e.g., cp38, abi3). Can be specified multiple times.

--no-binary
    Do not use pre-built binary packages (wheels) for . Forces downloading source distributions. Use :all: to apply to all packages.

--only-binary
    Do not use source distributions for . Forces downloading wheels. Use :all: to apply to all packages.

-i , --index-url
    Base URL of the Python Package Index (default: https://pypi.org/simple). Used to find packages.

--extra-index-url
    Extra URLs of package indexes to use in addition to --index-url. Can be specified multiple times.

--pre
    Include pre-release and development versions when searching for packages. By default, pip only considers stable versions.

--progress-bar
    Specify the type of progress bar: on, off, ascii, emoji, pretty.

--verbose
    Give more output, displaying debugging information.

DESCRIPTION

The `pip download` command fetches Python packages and their dependencies from the Python Package Index (PyPI) or other configured repositories and saves them to a local directory without performing an installation. This functionality is invaluable for creating an offline cache of packages, preparing distributions for air-gapped environments, or populating local package mirrors. It can download various distribution formats, including source distributions (e.g., `.tar.gz`) and pre-compiled binary wheels (`.whl`), allowing users to control the type of package fetched based on the target environment's needs. Unlike `pip install`, `pip download` focuses solely on acquiring the package files, making it a critical step in a robust package management workflow for complex or restricted setups.

CAVEATS

1. Environment Specificity: `pip download` by default attempts to download packages compatible with the current Python environment. For downloading packages intended for a different environment (e.g., a different OS or Python version), it is crucial to use explicit options like --platform, --python-version, and --implementation.
2. No Installation: This command only downloads distribution files. It does not perform any installation, compile C extensions, or run setup scripts. The downloaded files still need to be installed later using `pip install --no-index --find-links `.
3. Dependency Resolution: While `pip download` resolves and downloads dependencies by default, it does so based on the download environment's interpretation of metadata. Ensure that the options used accurately reflect the target installation environment to avoid missing or incompatible dependencies.

COMMON USE CASES

1. Offline Deployments: Download all required packages and their dependencies to a directory, then transfer them to an isolated environment for installation.
2. Reproducible Builds: Cache specific versions of packages locally to ensure consistent build environments across development, testing, and production.
3. Populating Local PyPI Mirrors: Use `pip download` to fetch packages and then populate a local simple HTTP server that acts as a private PyPI mirror.
4. Cross-Platform Packaging: By leveraging options like --platform and --python-version, developers can download wheels for target systems different from their current development environment.

DOWNLOADING SPECIFIC FORMATS

By default, `pip download` prefers wheels (`.whl`) if available, then falls back to source distributions (`.tar.gz`, `.zip`). You can control this behavior with:
--no-binary :all: to force downloading only source distributions for all packages.
--only-binary :all: to force downloading only wheels for all packages.

HISTORY

The `pip` command-line tool, a successor to `easy_install`, emerged around 2008 as the preferred package installer for Python. The `download` subcommand was specifically introduced to address the growing need for offline package management and reproducible builds. This became vital for scenarios involving air-gapped systems, corporate networks with restricted internet access, or the creation of local package mirrors, allowing users to pre-fetch and curate package distributions before deployment. Its development aligned with `pip`'s overall goal to provide more robust and reliable package management capabilities for the Python ecosystem.