Skip to main content

ISOx

Python PyPI License Release OS CI

A command-line tool for downloading and verifying Linux distribution ISOs.

isox alpine: four mirrors sampled, download from the fastest, checksum from Alpine's own host

Select distro -> Compare mirror speeds -> Download .iso -> Verify checksum
                                          (fastest mirror)  (distro's own host)

Already have an ISO? isox <distro> --verify FILE checks it against the distro's own checksum without downloading anything.

Why

Manually verifying checksums gets tedious quickly, making it easy to skip. Skipping verification can pose an integrity risk (modified ISOs, corruption, etc.), so ISOx automates the process.

I hope this tool makes getting started with Linux a little faster, easier, and safer for anyone who wants to use it.

Install

From PyPI:

pip install isox
isox arch

Or straight from a clone:

pip install .
isox arch

Usage

Once installed from PyPI, isox works as a bare command. From a clone, use python isox.py. Examples below use the clone form.

List every supported distro:

python isox.py --list

Save somewhere other than ./ISOx_Downloads:

python isox.py arch --output-dir /example/directory

Pick an older release instead of the newest:

python isox.py ubuntu-server --release 24.04
python isox.py proxmox --release 8
python isox.py mint --release 22        # newest 22.x

Verify an ISO you already have (from a browser, a torrent, a USB stick):

python isox.py fedora --release 44 --verify ~/Downloads/Fedora-Workstation-Live-44-1.7.x86_64.iso
python isox.py ubuntu --release 24.04 --verify ubuntu-24.04.5.1-desktop-amd64.iso

Features

  • Config-driven distro support - add supported distributions through distros.json without changing code.
  • Version-folder auto-discovery - for distros with no stable "latest" alias, the current version-numbered directory is discovered by scanning a parent directory and sorting versions (folder names).
  • Release selection - --release picks an older release, such as Ubuntu 24.04 or Proxmox 8. A partial version like 22 gets the newest release in that series.
  • Mirror selection - tests available mirrors and selects the fastest.
  • Resumable downloads - continues interrupted downloads, while discarding out of date copies.
  • Live progress bar - shows percentage and real-time throughput, and degrades to a plain byte counter if the server won't report a total size.
  • Verify existing ISOs - --verify checks a file you already have against the distro's checksum, without downloading or renaming anything.

Config format (distros.json)

Every distro entry needs mirrors, checksum_filename, and hash_algo at minimum. Everything else is optional and only needed if that distro deviates from the simplest cases.

If the included mirrors are not ideal for your location, you can easily update them. Just find a suitable mirror from the distro's official mirror list and replace the URL in distros.json. The tool will then handle the rest. HTTPS only.

{
    "arch": {
        "mirrors": ["https://fastly.mirror.pkgbuild.com/iso/latest/"],
        "checksum_base": "https://geo.mirror.pkgbuild.com/iso/latest/",
        "checksum_filename": "sha256sums.txt",
        "hash_algo": "sha256",
        "iso_filename": "archlinux-x86_64.iso"
    },
    "fedora": {
        "mirrors": [
            "https://dl.fedoraproject.org/pub/fedora/linux/releases/{version}/Workstation/x86_64/iso/",
            "https://mirror.cs.princeton.edu/pub/mirrors/fedora/linux/releases/{version}/Workstation/x86_64/iso/",
            "https://mirror.arizona.edu/fedora/linux/releases/{version}/Workstation/x86_64/iso/"
        ],
        "version_directory" : true,
        "version_discovery_url" : [
            "https://dl.fedoraproject.org/pub/fedora/linux/releases/",
            "https://mirror.arizona.edu/fedora/linux/releases/"
        ],
        "checksum_base": "https://dl.fedoraproject.org/pub/fedora/linux/releases/{version}/Workstation/x86_64/iso/",
        "checksum_filename" : "CHECKSUM",
        "checksum_discovery_method" : "html_scan",
        "checksum_format" : "bsd",
        "discovery_method": "html_scan",
        "hash_algo": "sha256",
        "iso_filename_contains": ["Workstation", "x86_64"]
    }
}

Checksum verification

The checksum is fetched on every run. Files that fail verification are renamed to .FAILED. Files that cannot be verified remain .UNVERIFIED.

Security

ISOx detects corruption, incomplete downloads, and ISOs that don't match their published checksums.

It does not authenticate the checksum itself. If a distribution's infrastructure is compromised, an attacker could replace both the ISO and its checksum.

ISOx does not verify GPG signatures. See SECURITY.md for details.

Requirements

  • Python 3.10+
  • requests
  • beautifulsoup4

Development

pip install -e '.[dev]'
pytest
black --check .
ruff check .
bandit isox.py

pytest -m live       # all distros
pytest -m live -s    # printing each resolved filename and hash
pytest -m live -k rocky

License

MIT License: see LICENSE for details. Feel free to use, modify, or build on this.

Metadata

Release files for isox 3.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for isox 3.9.0
File Size Uploaded Provenance Actions
isox-3.9.0.tar.gz 33.9 kB With provenance Details for isox-3.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for isox 3.9.0
File Interpreter ABI Platform Actions
isox-3.9.0-py3-none-any.whl Python 3 none any Details for isox-3.9.0-py3-none-any.whl

Total release size: 50.9 kB

Release files / isox-3.9.0.tar.gz

Download URL isox-3.9.0.tar.gz
Size 33.9 kB
Tags Source
SHA-256 checksum
How to use checksums
e0b485ac4a72bb58971b15b493280de37347590671cebfc440358f6d37871351
BLAKE2b-256 checksum
How to use checksums
01c61c9b655a854df2d30941eb826c54c1afedf201ca16b531d3503be98cfd19
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / isox-3.9.0-py3-none-any.whl

Download URL isox-3.9.0-py3-none-any.whl
Size 17.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3a6044fd1f276179b811ddf5535d50df3f02c33430fbded96ba540d9b18a4a16
BLAKE2b-256 checksum
How to use checksums
9211e6539a5d4f2e276342ec95549fc0b14151ca4962ea292ecde21669acbf6a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for isox 3.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for isox-3.9.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page