APT-TRANSPORT-MIRR(1)

🦋 apt-transport-mirr — the mirror-picking bestie 💅

okay so this is section 1 of the APT manual, APT-TRANSPORT-MIRR(1) — like, the page for apt-transport-mirror. sit down, bestie, we're learning how APT picks which mirror to hit ✨

---

✨ NAME ✨

apt-transport-mirror — the APT transport that does all the automated mirror selection for you 🎀

---

🌸 DESCRIPTION 🌸

Okay so first things first, bestie: this APT transport is not out here implementing its own protocol to reach local or remote repositories. Not its vibe. What it actually does is acquire a mirrorlist and then redirect every single request to whichever mirror(s) it picked from that list — and it reaches those mirrors through other transports, like apt-transport-http(1). iykyk 💅

The basic functionality has been around since apt 0.7.24, but it was literally undocumented until apt 1.6, which had a complete rework of the transport and everything it supports. glow-up fr fr 👑

also note: a transport is never called directly by a user. APT tools call it based on your configuration. so don't be out here invoking it yourself, that's not the assignment 🙈

If grabbing a file from a mirror fails, the method makes sure another possible mirror from the list gets tried automatically — it keeps going until either the file is retrieved or there's literally no mirror left in the list. So server downtimes and similar chaos get handled transparently. no cap, it just handles it 🫶

The security implications of this transport? They depend entirely on the security considerations of the transport used to acquire the mirrorlist and the transports involved in accessing the mirror(s) that got chosen. so, like, the vibes are inherited 💀

---

💖 OPTIONS 💖

This transport has no configuration options at present. zero. none. the mirror selection is based entirely on the mirrors offered in the mirrorlist and the files APT needs to acquire. that's it, that's the whole system 🌈

🎀 Mirrorlist format 🎀

A mirrorlist contains one or more lines, and each line specifies a URI for a mirror. Empty lines and lines starting with a hash character (#) are ignored — comments, slay ✨

A URI always starts with a URI scheme, and that scheme defines which transport gets used for this mirror. So if, for example, the URI starts with http:, the responsible transport is apt-transport-http(1) — and that transport might have its own specific requirements for the format of the rest of the URI. not our problem, talk to them 💅

Metadata about a mirror can go on the same line, separated from the URI by a tab. Multiple items of metadata can themselves be separated by either tabs or spaces. (This is an advanced feature, only available with apt >= 1.6. Earlier apt versions will fail to parse mirrorlists that use it — so like, know your audience 😭)

Since apt 1.6, compressed mirrorlists are also supported. But the filename of the mirrorlist must specify the compression algorithm used — there is no auto-detection based on file contents. no guessing, bestie, you have to actually say it 🔥

🦋 Mirror selection by metadata 🦋

So as we said in the format section, a mirror can have additional metadata attached to it, and that metadata prevents the mirror from being selected for acquiring a file that doesn't match. This way a mirrorlist can, for example, contain partial mirrors that only serve certain architectures — and APT will automatically choose a different mirror for files requiring an unlisted architecture. iconic behaviour 👑

Here's what's supported:

• arch — limits for the architecture
• codename — codename of the release
• component — component of the repository the file is in
• lang — language the file applies to
• suite — suite name of the release
• type — type of the file

⭐ Fallback order for mirrors ⭐

If no priority is given for a mirror via the metadata key priority, the order in which mirrors are contacted is random. yeah. random. 🎲

But if a certain set of mirrors should be tried first before any of another set, you can explicitly set a priority. The mirrors with the lowest number are tried first. Mirrors with no explicit priority set default to the highest possible number, so they get tried last. And the choice between mirrors with the same priority is again random. chaos, but organized chaos 💜

Now here's the fun part — files are by default spread over multiple mirrors of the set with the lowest priority number:

• At least three mirrors are used if the set contains enough mirrors
• Beyond that, their number scales with the square root of the number of files fetched — e.g. 4 mirrors for 16 files, 10 mirrors for 100 files
• Each file is assigned to the currently least used of these mirrors

This fan-out can be controlled via the apt.conf(5) options:

• Acquire::Mirror::Fanout — sqrt (the default) or none to pick a random mirror for each file independently
• Acquire::Mirror::Fanout-Limit — an upper bound on the number of actively used mirrors, 0 for no limit

Mirrors of another set are only tried on failure, as described above. so like, only when things go wrong 😭

🌸 Allowed transports in a mirrorlist 🌸

The availability and choice of transports in a mirrorlist is limited by how the APT client is accessing the mirrorlist.

• If a local transport like file or copy is used, the mirrorlist can also include local sources
• A mirrorlist accessed via http can not do that
• Additionally, a mirrorlist can not contain a mirrorlist or other wrapping transports (like apt-transport-tor)

See the documentation of those transports for how to use them with the mirror method 📚

Note that apt versions before 1.6 do not support any other transport than http. periodt.

---

🌈 EXAMPLES 🌈

🍓 Basic example 🍓

A basic mirrorlist example, supported by all apt versions with a mirror method (>= 0.7.24), in which the client will pick any of the three mirrors:

http://ftp.de.debian.org/debian/
http://ftp.us.debian.org/debian/
http://deb.debian.org/debian/

Assuming a file with this content is stored as /etc/apt/mirrorlist.txt on your machine, it can be used like this in sources.list(5) (since apt 1.6):

deb mirror+file:/etc/apt/mirrorlist.txt trixie main

All versions of the mirror method support a mirrorlist accessible via HTTP, so assuming it's available at http://apt.example.org/mirror.lst, the sources.list entry from above could instead be written as:

deb mirror://apt.example.org/mirror.lst trixie main

Note that since apt 1.6, the use of mirror+http should be preferred over mirror for uniformity. The functionality is the same. same energy, better syntax 💅

🧚 Example with metadata-enhanced mirror selection 🧚

As explained in the format definition, apt versions before 1.6 do not support this and will fail parsing the mirrorlist. so like, update, bestie 😭

This example mirrorlist is intentionally complicated to show some aspects of the selection. The following setup is assumed:

• The first mirror is a local mirror accessible via the file method, but potentially incomplete
• The second mirror has a great connection, but is a partial mirror insofar as it only contains files related to the architectures amd64 and all
• The remaining mirrors are average mirrors which should be contacted only if the earlier ones didn't work

file:/srv/local/debian/mirror/     priority:1 type:index
http://partial.example.org/mirror/ priority:2 arch:amd64 arch:all type:deb
http://ftp.us.debian.org/debian/   type:deb
http://ftp.de.debian.org/debian/   type:deb
https://deb.debian.org/debian/

In this setup, with this mirrorlist:

• The first mirror will be used to download all index files, assuming the mirrorlist itself is accessed via a local transport like file
• If it isn't, if the mirror is otherwise inaccessible, or if it doesn't contain the requested file, another mirror will be used to acquire the file — chosen depending on the type of the file:
  • An index file will be served by the last mirror in the list
  • A package of architecture amd64 is served by the second
  • Those of e.g. architecture i386 by one of the last three

it's giving load balancing, honestly 🔥

---

💀 BUGS 💀

APT bug page[1]. If you wish to report a bug in APT, please see /usr/share/doc/debian/bug-reporting.txt or the reportbug(1) command. go off, file that bug 🫶

---

👑 AUTHOR 👑

APT team

---

📝 NOTES 📝

1. APT bug page https://bugs.debian.org/src:apt

---

okay that's the whole page, bestie, you're officially educated 💖 this was APT 3.3.5, dated 20 July 2026 — go forth and let your mirrors pick themselves, mwah 🎀✨