setuptools-download: Setuptools Plugin for External File Downloads

1.1.0 · active · verified Sat Apr 11

setuptools-download is a plugin for setuptools that enables the declarative downloading of external files as part of a Python package's build process. It allows specifying URLs, SHA256 checksums, and extraction methods (zip, tar) directly within the `pyproject.toml` or `setup.cfg` file. Currently at version 1.1.0, it is actively maintained with infrequent but targeted releases.

Warnings

gotcha The `sha256` checksum is a mandatory field for every download entry. Omitting it will result in a build error. This is a security feature to ensure the integrity and authenticity of downloaded files.
Fix: Always provide the correct SHA256 checksum for each file you intend to download.
gotcha This plugin is designed for declarative configuration via `pyproject.toml` or `setup.cfg`. While `setuptools` still supports `setup.py`, relying on direct programmatic usage within `setup.py` for `setuptools-download`'s features is not the intended or documented pattern and may not work as expected.
Fix: Prefer using `pyproject.toml` (recommended) or `setup.cfg` to define download operations.
breaking As a plugin, setuptools-download operates within the setuptools build environment. Frequent breaking changes in upstream `setuptools` (e.g., removal of `setup.py` commands, stricter configuration parsing, changes to internal APIs) can indirectly affect this plugin's functionality or the project's ability to build. Users should pin specific versions of `setuptools` for stability.
Fix: Pin your `setuptools` version in `pyproject.toml`'s `build-system.requires` (e.g., `setuptools>=61.0,<80.0.0`) and regularly test against newer `setuptools` releases.

Install

pip install setuptools-download Install latest version

Quickstart

setuptools-download is configured declaratively, typically in `pyproject.toml` under the `[tool.setuptools-download]` section. Each download is defined by a unique key (e.g., `download_example_asset`) with required `url` and `sha256` fields, and an optional `dest` field. After configuration, running `python -m build` will execute the download as part of the source distribution (sdist) or wheel (bdist_wheel) build process. Replace `url` and `sha256` with your actual file and its checksum.

# pyproject.toml
[build-system]
requires = ["setuptools>=61.0", "setuptools-download==1.1.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package-with-downloads"
version = "0.0.1"
description = "A package that downloads an external file during build"
readme = "README.md"
requires-python = ">=3.8"

[tool.setuptools-download]
# Define a download target: key is an arbitrary name, value is a table of settings
download_example_asset = {
    url = "https://example.com/sample.txt",
    sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", # SHA256 of an empty file, replace with actual asset's SHA256
    dest = "src/my_package/data/sample.txt"
}

# To build the package (which triggers the download):
pip install build
python -m build

view raw JSON →