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.8.1

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.8.1
File Size Uploaded Provenance Actions
isox-3.8.1.tar.gz 32.8 kB With provenance Details for isox-3.8.1.tar.gz

Built distribution (wheel)

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

Total release size: 49.3 kB

Release files / isox-3.8.1.tar.gz

Download URL isox-3.8.1.tar.gz
Size 32.8 kB
Tags Source
SHA-256 checksum
How to use checksums
a0a1c762aaf95ff8873f2bd1b004fad43e281c4b641797c58b16a89e59cd0a2e
BLAKE2b-256 checksum
How to use checksums
c103197933bbd1561e0c182182a68c04a898782867b3cfcb3fd029d78c30429c
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 5, 2026.

Transparency log

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

Download URL isox-3.8.1-py3-none-any.whl
Size 16.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fd8af0dcbd92828b4bbd1b0ae01dd7f515d0081e379847d72c69d19c27c70002
BLAKE2b-256 checksum
How to use checksums
3a85bb5cbef234f016ac566e8e988039599a18059d4e7c54dbc854da1b5518b0
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 5, 2026.

Transparency log

Security for isox 3.8.1

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.8.1.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 5, 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