model-downloader-util

Download or resolve model files from local paths, HTTP(S), S3-compatible storage (S3, MinIO, RustFS), Google Cloud Storage, and Git LFS.

Install

pip install modeldownloaderutil

From source:

uv sync

Usage

from modeldownloaderutil import download_model, cache_dir

path = download_model("s3://my-bucket/models/weights.onnx")
path = download_model("https://example.com/model.onnx", force_download=True)

Supported sources

Cache

Default: platformdirs cache for model_registry (override with MODEL_CACHE_DIR).

<cache>/
  s3/<bucket>/<key>
  gs/<bucket>/<object>
  url/<host>/<path>
  git/<repo_slug>/<file_path>
  git/<repo_slug>.lock   # serializes parallel Git / Git LFS pulls for the same repo

Progress

HTTP(S), S3/MinIO/RustFS, GCS, and Git LFS show tqdm byte bars. Plain Git clones/pulls stream native git --progress to stderr. Disable with MODEL_DOWNLOAD_PROGRESS=0 (or TQDM_DISABLE=1).

Environment

Copy .env.example to .env in the project root (loaded automatically on download_model).

Development

make test
make build

Publish to PyPI

Create an API token at pypi.org (scope: project modeldownloaderutil or entire account).

export UV_PUBLISH_TOKEN=pypi-xxxxxxxx
make publish

Dry run on TestPyPI first:

export UV_PUBLISH_TOKEN=pypi-xxxxxxxx
make publish-test
pip install --index-url https://test.pypi.org/simple/ modeldownloaderutil