{"id":3802,"library":"setuptools-download","title":"setuptools-download: Setuptools Plugin for External File Downloads","description":"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.","status":"active","version":"1.1.0","language":"python","source_language":"en","source_url":"https://github.com/asottile/setuptools-download","tags":["setuptools","packaging","build-system","download","declarative"],"install":[{"cmd":"pip install setuptools-download","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This library is a plugin for setuptools and requires it to function. It should be listed in your build-system requirements.","package":"setuptools","optional":false}],"imports":[],"quickstart":{"code":"# pyproject.toml\n[build-system]\nrequires = [\"setuptools>=61.0\", \"setuptools-download==1.1.0\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"my-package-with-downloads\"\nversion = \"0.0.1\"\ndescription = \"A package that downloads an external file during build\"\nreadme = \"README.md\"\nrequires-python = \">=3.8\"\n\n[tool.setuptools-download]\n# Define a download target: key is an arbitrary name, value is a table of settings\ndownload_example_asset = {\n    url = \"https://example.com/sample.txt\",\n    sha256 = \"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\", # SHA256 of an empty file, replace with actual asset's SHA256\n    dest = \"src/my_package/data/sample.txt\"\n}\n\n# To build the package (which triggers the download):\npip install build\npython -m build\n","lang":"toml","description":"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."},"warnings":[{"fix":"Always provide the correct SHA256 checksum for each file you intend to download.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Prefer using `pyproject.toml` (recommended) or `setup.cfg` to define download operations.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"setuptools versions >=70.0.0, >=78.0.0, >=80.0.0"}],"env_vars":null,"search_vec":"'1.1.0':56 'activ':59 'allow':36 'build':33,69 'build-system':68 'checksum':40 'current':53 'declar':21,72 'direct':46 'download':3,9,12,22,71 'enabl':19 'extern':7,24 'extract':42 'file':8,25,52 'infrequ':62 'maintain':60 'method':43 'packag':31,67 'part':27 'plugin':5,15 'process':34 'pyproject.toml':49 'python':30 'releas':65 'setup.cfg':51 'setuptool':2,4,11,17,66 'setuptools-download':1,10 'sha256':39 'specifi':37 'system':70 'tar':45 'target':64 'url':38 'version':55 'within':47 'zip':44","created_at":"2026-04-11T17:45:19.770375+00:00","updated_at":"2026-04-16T21:38:04.019627+00:00","problems":[{"fix":"Add `setuptools-download` to the `build-system.requires` list in `pyproject.toml` (e.g., `requires = [\"setuptools>=61.0\", \"setuptools-download\"]`) or `setup_requires` in `setup.py`.","cause":"`setuptools-download` is not correctly specified as a build dependency, preventing setuptools from recognizing its custom `download_data` option.","error":"Unknown distribution option: 'download_data'"},{"fix":"Update the SHA256 checksum in your `pyproject.toml` or `setup.cfg` to match the correct hash of the downloaded file, or verify the URL points to the expected file.","cause":"The SHA256 checksum specified in the package configuration (`pyproject.toml` or `setup.cfg`) does not match the actual checksum of the file downloaded from the provided URL.","error":"setuptools_download.DownloadError: SHA256 checksum mismatch for URL: <your_url_here>"},{"fix":"Verify the URL is correct and accessible, check your internet connection, ensure any proxy settings are configured properly, or try downloading the file manually to diagnose the issue.","cause":"The package failed to download the external file, typically due to network connectivity issues, an invalid URL, a server error (e.g., 404 Not Found), or proxy problems.","error":"setuptools_download.DownloadError: Failed to download from URL: <your_url_here> - <exception_details>"},{"fix":"Review your `download_data` configuration in `pyproject.toml` or `setup.cfg` against the `setuptools-download` documentation to ensure all required fields are present and correctly formatted.","cause":"The `download_data` configuration in `pyproject.toml` (or `setup.cfg`) does not conform to the expected schema, often due to missing required keys like `url` or `sha256`, or incorrect data types.","error":"jsonschema.exceptions.ValidationError: <validation_error_details>"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/asottile/setuptools-download","docs":null,"changelog":null,"pypi":"https://pypi.org/project/setuptools-download/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-11","next_check":"2026-07-10","install_tag":null}}