rate-mirrors: a mirror list ranked by the speed you actually measure

A mirror list ordered by what your connection measures

rate-mirrors is described as an everyday-use client-side map-aware mirror ranking tool for Arch Linux, Manjaro and custom mirror lists. The core claim is that it finds the best mirrors for your distribution, and the mechanism is that it uses submarine cable and internet exchange data to intelligently hop between countries and discover fast mirrors in about 30 seconds.

The word client-side is doing real work in that sentence. This is not a service that ranks mirrors from a data centre, and it is not a static list sorted by some global score. The ranking is produced by running download speed tests from the machine you are sitting at, over your own connection, at the moment you run it.

That is the whole point of the design, and it is also its limit. A mirror that is fast for a user in one country can be slow for everyone else, and the only way to know which mirror is fast for you is to measure it from where you are. The tool's job is to make that measurement cheap by not testing every mirror in the world, and by going to the promising countries in a sensible order.

The output is a mirrorlist in the format pacman expects, including the Server lines with the $repo and $arch variables, optionally with comments recording when the run started, how many mirrors were fetched, how many survived filtering and what each speed test found.

Replacing the mirrorlist is one pipeline

The quick start is a shell pipeline, and for Arch Linux it is a single command:

# Arch Linux
rate-mirrors arch | sudo tee /etc/pacman.d/mirrorlist

# Manjaro
rate-mirrors manjaro | sudo tee /etc/pacman.d/mirrorlist

The safer version keeps a backup, which is worth preferring on a machine you care about:

export TMPFILE="$(mktemp)"; \
    rate-mirrors --save=$TMPFILE arch --max-delay=21600 \
    && sudo mv /etc/pacman.d/mirrorlist /etc/pacman.d/mirrorlist-backup \
    && sudo mv $TMPFILE /etc/pacman.d/mirrorlist

And the full option list is one command away, rate-mirrors --help.

One detail in the usage section removes a common worry: the tool doesn't need root. You are only root when you write to /etc/pacman.d, and the tool itself refuses to run as root unless you pass --allow-root. That is a sensible default for something that makes network requests to a list of servers on your behalf.

The everyday use case in the documentation wraps the whole update cycle into an alias, saving the old mirrorlist, running the ranking, dropping the package caches with paccache, and finishing with yay -Syyu. The notes explain the pieces: sudo true prompts for the password at the start, paccache comes from pacman-contrib, and yay is an AUR helper.

Five ways to get it, including a musl static build

The installation table covers a lot of ground, and the notes in it are the useful part.

On Arch Linux the default is the official package, sudo pacman -S rate-mirrors, a pre-built dynamically linked glibc binary. The AUR offers two more: yay -S rate-mirrors-bin is pre-built and statically linked against musl, and yay -S rate-mirrors-git builds from source with a dynamically linked glibc.

On OpenBSD it is pkg_add rate-mirrors from ports. There are pre-built binaries on the GitHub releases page. And from source, cargo build --release --locked, which needs a Rust toolchain.

The distinction between the glibc and musl builds is not cosmetic. A statically linked musl binary has no shared library dependencies at all, so it runs on a system whose glibc is older than the one it was built against, which is a common way to end up with a broken package after a system upgrade or on a minimal installation. The Makefile in the repository has the two targets that produce them:

cargo build --release --locked --target=x86_64-unknown-linux-gnu
cargo build --release --locked --target=x86_64-unknown-linux-musl

The package metadata gives the toolchain requirements: Rust edition 2024, rust-version 1.85, and the crate is named rate_mirrors with the author listed as Nikita Almakov. The runtime dependencies are small and modern, with reqwest configured for JSON, HTTP/2 and rustls with native roots, tokio with the full feature set, clap with the env feature, and nix, rand, chrono, regex, url and select for the rest.

How the country hopping actually works

The algorithm section describes a process rather than a formula, and it is the part that makes the tool fast.

For the Arch example it goes like this. First the tool fetches mirrors from the Arch Linux Mirror Status JSON feed. Then it filters out incomplete or outdated mirrors. Then it sorts by mirror score. Then, starting from the entry country, it finds neighbouring countries, using major internet hubs for the first two jumps and geographic proximity for every jump after that. It tests mirrors from each country and tracks the fastest and the lowest latency. Then it jumps to the countries of the best mirrors and repeats. After the maximum number of jumps it re-tests the top mirrors sequentially and outputs the final ranking.

The data behind those decisions is submarine cable connections, internet exchange locations and counts per country, and continental groupings for geographic proximity. The cable and exchange data comes from TeleGeography, and the attribution is stated in the documentation.

The output example in the README shows what a run looks like. It fetched 1147 mirrors, 730 were left after filtering, and the exploration log shows the first jump exploring the United States and finding the United Kingdom and Germany as neighbours, one by hubs and one by distance. The final re-test produced three ranked entries with speeds around 54 to 65 MB/s, and the whole run took about nineteen seconds in that example, close to the 30 seconds the description promises.

The sequential final re-test is the part that matters for accuracy. The exploratory phase runs many tests in parallel, which is fast but gives noisy numbers, so the winners are measured again one at a time before they are ranked.

The options decide how much of the world you probe

The common options are where the cost and the coverage are controlled.

--concurrency=N sets the number of simultaneous speed tests and defaults to 16. --max-jumps=N caps the number of country hops and defaults to 7, which is what stops the search from wandering. --entry-country=CC sets the starting country code and defaults to US, which is a surprising default for most of the world and is the first thing to change.

Country filtering comes in two mutually exclusive forms. --exclude-countries=CC,CC removes the listed codes, and --include-countries=CC,CC keeps only the listed ones, where ZZ stands for unknown. --protocol=PROTO restricts testing to http or https only. --max-mirrors-to-output=N caps how many mirrors end up in the list, which matters if you want a short list rather than a long one.

Two flags change the failure behaviour. --disable-comments turns off the header comments in the output. --disable-untested-fallback makes the tool exit with an error when all speed tests fail, instead of outputting untested mirrors, which is the difference between a mirrorlist you can trust and one that might point at a server that never answered you.

The subcommand options are narrower. --completion=N sets a minimum sync completion between 0.0 and 1.0, defaulting to 1.0, so by default a mirror that is not fully in sync is discarded. --sort-mirrors-by=MODE accepts score_asc, score_desc, delay_asc and delay_desc, with score_asc as the default, and it is worth understanding that the default ranking is by the mirror's own score rather than by the speed you measured.

Custom mirror lists go in through stdin

The stdin subcommand is what makes this more than an Arch tool, and it is the most interesting part of the documentation.

It exists for custom mirror lists or for distributions that are not supported. The input is tab separated and flexible about order: a line can be a URL on its own, a country code followed by a tab and the URL, or the URL followed by a tab and the country code. The country is optional, and a mirror with no country is simply tested where it is listed.

The invocation in the documentation shows the three things you have to tell it:

cat mirrors.txt | rate-mirrors --concurrency=40 stdin \
    --path-to-test="extra/os/x86_64/extra.files" \
    --path-to-return='$repo/os/$arch' \
    --comment-pref

--path-to-test is the file the speed test fetches from each mirror, and for Arch that is the repository metadata file rather than a large package, which keeps the test cheap. --path-to-return is the template for the mirrorlist entry, and the dollar-repo and dollar-arch variables are the pacman placeholders. --comment-pref adds the comment prefix to the generated entries. The repository even ships a stdin.txt at the root, which is presumably a starting point for the format.

Note the concurrency of 40 there, well above the default of 16, which is what you would do if you have a list you trust and want the answer quickly.

The licence is the thing to check before you install it

The licence information in this repository is contradictory, and it is the kind of contradiction that a careful reader should stop on.

The README badge says License: CC BY-NC-SA 3.0, the Creative Commons Attribution-NonCommercial-ShareAlike licence. The licence field on the repository itself is recorded as a custom licence that GitHub cannot classify. The LICENSE file in the repository is the authority, and the two summaries do not obviously agree.

That matters more than usual here, because a Creative Commons share-alike licence with a non-commercial clause is a strange fit for a distributed binary, and a company shipping this tool inside an image or a product would need to read the actual file rather than the badge. This article is not legal advice and cannot tell you what the file says, but it can tell you that the two places that claim to summarise it disagree.

On maintenance, the project is not archived, the last push was on 2026-10-18, and the release history shows v0.34.0 on the same day, v0.33.0 on 2026-09-18 and v0.32.0 on 2026-09-13. That is a steady monthly cadence with patch releases in between, and the CHANGELOG.md and a Makefile at the root are there to support it.

The final limitation is not about the software but about what it can fix. A mirror list is only as good as the mirrors in it. If your downloads are slow because your current mirror is overloaded, or because the route to your country's mirrors is congested, ranking will find a different path at best. rate-mirrors optimises the choice of server, not the quality of the origin, and for a package set that is genuinely slow everywhere it will simply reorder a list of equally slow mirrors.

Editorial conclusion

Adopt rate-mirrors if your Arch or Manjaro downloads are slow because your configured mirror is far away, and you are willing to re-run a ranking that probes dozens of mirrors over your own connection. Do not adopt it if the problem is a slow origin server or a congested link to your mirror, since ranking cannot fix either, and read the LICENSE file before using it in a commercial context, because the licence badge and the repository metadata do not agree. Verify first that the tool can reach the mirror status feed, that the entry country and hop limit suit your location, and that the generated mirrorlist has a backup before it replaces the one pacman is using.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. westandskif/rate-mirrors on GitHub