os-download 0.1.4

os-download is a two-command Python CLI that finds the latest download URL for 15 popular OS ISO families and pulls them to disk — with signature-checked verification, working resume, parallel and multi-connection downloads, and automatic retries.

os-finder          # resolve latest ISO URLs for all supported OSes
os-download        # download everything that was found, verifying as it goes

Supported operating systems

Signed means the checksum file itself is verified against a signing key that os-download pins — a mirror cannot forge it. SHA256 means the hash is checked, which proves the download is intact but not that the mirror was honest. See Verification.

Windows 11 — Microsoft's ISO download requires a JavaScript session-token flow that cannot be replicated with plain HTTP. os-download delegates this to Mido, which is fetched at a pinned commit on first use.

Requirements

• Python 3.10 or newer (3.9 and earlier are not supported)
• Linux, macOS, or Windows

Two optional binaries unlock more, and os-download works without either:

# Debian / Ubuntu
sudo apt install gnupg aria2

# Fedora
sudo dnf install gnupg2 aria2

# Arch
sudo pacman -S gnupg aria2

# macOS
brew install gnupg aria2

Installation

os-download is on PyPI. Either installer puts os-finder and os-download on your PATH in an isolated environment, available from any directory.

With uv (recommended)

# 1. Install uv (skip if you already have it)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Install os-download
uv tool install os-download

# Upgrade to the latest version at any time
uv tool upgrade os-download

# Uninstall
uv tool uninstall os-download

With pipx

pipx install os-download

Bleeding edge

To install the current main rather than the latest release:

uv tool install git+https://github.com/dragonfoxsl/os-download

Development install

git clone https://github.com/dragonfoxsl/os-download
cd os-download
uv sync --locked

# Run from the project directory
uv run os-finder
uv run os-download

Usage

Step 1: Find ISO URLs

# All supported OSes (runs in parallel)
os-finder

# Specific OSes
os-finder --os ubuntu fedora opensuse arch linuxmint rocky

# Save URLs to a custom path
os-finder --output ~/isos/urls.txt

# Increase timeout for slow connections
os-finder --timeout 30

# Machine-readable JSON output
os-finder --json

# Check every OS still resolves to an ISO (exits non-zero if a mirror moved)
os-finder --check

Mirrors reorganise their directory layouts, which makes a finder quietly stop resolving. --check is the same check a scheduled workflow runs weekly against the live mirrors, so a broken finder surfaces as a GitHub issue rather than a surprise at download time.

Step 2: Download

# Download everything found
os-download

# Three simultaneous downloads
os-download --parallel 3

# Skip verification (it is on by default)
os-download --no-verify

# Refuse anything not signed by a pinned distribution key
os-download --require-signature

# Faster: split each file across 16 connections (needs aria2c)
os-download --connections 16

# Force the built-in backend even if aria2c is installed
os-download --backend python

# Give up sooner on a flaky link (each retry resumes)
os-download --retries 1

# Download to a specific directory
os-download --dir /mnt/nas/isos

# Single URL
os-download --url "https://example.com/file.iso"

# Skip automatic decompression of .bz2 / .gz files
os-download --no-decompress

Interrupted downloads resume where they left off — re-run the same command. A dropped connection is retried automatically without failing the file. --output accepts a filename only; use --dir to choose its directory. Batch downloads stop before transfer when multiple URLs resolve to the same filename.

Keyboard shortcuts (download dashboard)

Download dashboard

When downloading multiple files, os-download shows a live dashboard:

• Header — active / done / failed counts, total data downloaded, speed sparkline, elapsed time
• Files — one progress bar per file with size, speed, and ETA
• Footer — keyboard shortcuts and current session settings

On completion the dashboard transitions to a summary panel showing files downloaded, total data, time taken, and any failures. If downloads fail you are prompted to retry them; the retry runs only the failed files.

At startup, if an existing file is detected you are prompted to resume or start from scratch. The server's byte range is validated before anything is appended; a malformed resume response is discarded and restarted safely.

Screenshots

Verification

Every download is verified by default. Two things are checked, in this order:

1. The signature on the checksum file. A hash fetched from the same mirror as the ISO only proves the download was not truncated — whoever can serve a bad ISO can serve a matching hash. Ubuntu, Debian, Linux Mint and Fedora sign their checksum files, and their signing keys are pinned in downloader/signatures.py. Keys are only ever imported by pinned fingerprint, or from a keyring published over HTTPS by the distribution itself (Fedora rotates its key every release), so a mirror can never introduce a key of its own.
2. The SHA256 hash of the file, once the document it came from is known to be authentic.

A file that fails verification is renamed to <name>.corrupt rather than left in place, so a later resume cannot append to bad bytes. Authentically verified files record a .verified marker, so a multi-gigabyte ISO is not re-hashed on every run. Unsigned hash-only results are always checked again and never satisfy --require-signature through the cache.

Signature verification needs gpg on PATH; without it, verification falls back to hash-only and says so.

All flags

os-finder

os-download

How it works

os-finder                          os-download
─────────────────────────────      ─────────────────────────────
MultiOSDownloadFinder              DownloadManager
  └─ runs all finders in             └─ reads ./os-links/all_os.txt
     parallel via                       runs downloads in parallel
     ThreadPoolExecutor                 via ThreadPoolExecutor

Each finder (BaseOSFinder          Each download
subclass) is independent:            • aria2c, or streams in chunks
  • scrapes its source               • resumes via Range header
  • verifies the URL                 • retries dropped connections
  • returns {variant: url}           • checks signature, then hash
                                     • decompresses .bz2/.gz
                                     • mido:// URIs delegated to Mido

Backends: aria2c when installed (several connections per file), the built-in one otherwise, and curl as a fallback for mirrors that reject the library outright with a 403.

Adding a new OS

1. Add a finder module under src/os_download/finders/ that subclasses BaseOSFinder from src/os_download/finders/base.py:

class MyOSFinder(BaseOSFinder):
    def __init__(self, timeout: int = 15):
        super().__init__("My OS", timeout)

    def find_download_links(self) -> dict[str, str]:
        try:
            # fetch, scrape, return {variant: url}
            return {"amd64": "https://..."}
        except Exception as exc:
            # Mirror lookups fail routinely. Log why, or a layout change becomes an
            # unexplained "not found".
            self.log_failure(exc)
            return {}

2. Register it in src/os_download/finders/registry.py:

'myos': MyOSFinder(timeout),

3. Add 'myos' to OS_CHOICES so src/os_download/cli/finder.py exposes it through --os.

Releasing

Pushing a vX.Y.Z tag publishes to PyPI. The workflow authenticates with a Trusted Publisher over OIDC, so no API token is stored anywhere.

# 1. Bump the version in BOTH places — the workflow aborts if the tag does not match
#    pyproject.toml            version = "0.1.4"
#    src/os_download/__init__.py   __version__ = "0.1.4"

# 2. Update the README for anything user-facing (flags, defaults, behaviour), and
#    regenerate the screenshots if the CLI or dashboard changed
uv run python scripts/render_help_svg.py
uv run python scripts/render_dashboard_svg.py
pnpm install --frozen-lockfile
pnpm exec playwright install chromium
pnpm render-images

# 3. Verify
uv sync --locked && uv run ruff check && uv run pytest -q && uv build

# 4. Tag and push
git tag -a v0.1.4 -m "os-download 0.1.4" && git push origin v0.1.4

Get the README right before tagging: the PyPI project page is baked in at upload time, so a later README fix will not appear there without a new release. A published version can be yanked but never re-uploaded.

Contributing and security

See CONTRIBUTING.md for development and pull-request checks. Report suspected vulnerabilities privately by following SECURITY.md.

Credits

License

MIT