Skip to main content

ISOx

Python PyPI License Release OS CI

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

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

Downloaded ISOs are saved to the created folder ISOx_Downloads/. Output looks like:

https://fastly.mirror.pkgbuild.com/iso/latest/archlinux-x86_64.iso sampled at 3.33 MB/s
https://geo.mirror.pkgbuild.com/iso/latest/archlinux-x86_64.iso sampled at 1.98 MB/s
https://mirror.rackspace.com/archlinux/iso/latest/archlinux-x86_64.iso sampled at 0.08 MB/s
Downloading archlinux-x86_64.iso from https://fastly.mirror.pkgbuild.com/iso/latest ...
[##############################] 100.0%    3.41 MB/s
Checksum matches, file is good.

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.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.8.0
File Size Uploaded Provenance Actions
isox-3.8.0.tar.gz 32.6 kB With provenance Details for isox-3.8.0.tar.gz

Built distribution (wheel)

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

Total release size: 49.0 kB

Release files / isox-3.8.0.tar.gz

Download URL isox-3.8.0.tar.gz
Size 32.6 kB
Tags Source
SHA-256 checksum
How to use checksums
d5207b583d82564676bbda5a8260b9ce4a7838c71a4a026d0bc6d380b49e9c01
BLAKE2b-256 checksum
How to use checksums
83cbba273f22d6044e10cdad39e424ecbcc8329549cc63ea7f45684cef5d9245
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 1, 2026.

Transparency log

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

Download URL isox-3.8.0-py3-none-any.whl
Size 16.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
817e6862f298379562252700da3ee2b4875040c28c48219ab36e00fd3323d391
BLAKE2b-256 checksum
How to use checksums
94ec45f68cb941986b56e6b1b714e7caabc5e7b8166809432803b6e8a262a9ca
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 1, 2026.

Transparency log

Security for isox 3.8.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.8.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 1, 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