Learn Aria2 - Metalink Download

#Introduction

In episode 9 you relied on the swarm to find sources. In earlier episodes you supplied mirror lists manually through an input file. What if there were a format that summarized all of that — mirrors, checksums, even torrents — in a single file that aria2 reads directly? That's Metalink, and it's one of aria2's greatest, least-understood strengths.

The simple intuition: you already know how to download from many sources. Metalink is a way to describe those sources in a structured form, complete with data-integrity guarantees. In the automation world, a description file like this is far more valuable than a series of ad hoc flags.

#What Is Metalink

Metalink is an XML format that describes one or several files along with every way to obtain them. Two variants are in circulation: .meta4 (Metalink version 4, standardized in RFC 5854) and .metalink (the older version 3). aria2 reads both without any extra plugins.

<?xml version="1.0" encoding="UTF-8"?>
<metalink xmlns="urn:ietf:params:xml:ns:metalink">
  <file name="debian-live-12.iso">
    <size>3584000000</size>
    <hash type="sha-256">4e3b7c2a9f1d5e6b8c7a1f2e3d4c5b6a7f8e9d0c</hash>
    <url>https://mirror1.example.com/debian-live-12.iso</url>
    <url>https://mirror2.example.com/debian-live-12.iso</url>
    <metaurl mediatype="torrent">https://mirror1.example.com/debian-live-12.iso.torrent</metaurl>
    <pieces length="1048576">
      <hash type="sha-1">a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0</hash>
    </pieces>
  </file>
</metalink>

The key elements: url for HTTP/HTTPS/FTP mirrors, hash for the whole-file checksum, pieces for per-chunk checksums, and metaurl for pointing to a companion torrent. One description file, many paths to the same file.

#Downloading from Metalink

Running aria2 with Metalink is as easy as giving it the file's path or URL:

aria2c debian-live-12.meta4

aria2c -d /srv/iso https://mirror1.example.com/debian-live-12.meta4

When what's downloaded is a .meta4 file, aria2 parses it automatically (--follow-metalink is enabled by default) and creates downloads for the files inside. All available mirrors are used at once — cross-server multi-source, not just cross-connection. If one mirror dies or slows down, aria2 simply glances at another mirror without any intervention from you.

#Automatic Checksum Verification

This is Metalink's biggest selling point. When pieces provides per-chunk checksums, aria2 validates the data during the download — every chunk that arrives is checked, and corrupted chunks are re-downloaded. You don't have to wait for the file to finish to know it's corrupted.

Compare that with plain HTTP: there you must download, then check the hash manually, and if it's corrupt, start over. With a Metalink carrying piece checksums, verification is fused into the download process. For large files like ISOs, this saves a very significant amount of time. If only a whole-file hash is available, verification happens once the file is complete — still automatic, just not per-piece.

To re-check a file already on disk, combine it with --check-integrity (or -V): aria2 validates again without re-downloading when everything matches.

#Combining HTTP and BitTorrent

Metalink version 4 can carry a torrent through the metaurl element with mediatype="torrent". Here's where aria2 shows its most distinctive capability: it downloads the same file over HTTP and BitTorrent simultaneously.

aria2c -d /srv/iso --metalink-file=debian-live-12.meta4

Chunks obtained from HTTP mirrors are uploaded to the swarm, and chunks from peers add speed. The two sources complement each other — when one path is slow, the other compensates. Since every chunk is guaranteed by a checksum, there's no risk of mixing data from two different sources. This is cross-protocol multi-source delivered by a single description format.

#Downloading Specific Files

A Metalink can hold many files in one document. Just like with torrents, you can inspect the list and then select:

aria2c --show-files release.meta4

aria2c --select-file=1-3 release.meta4

The same pattern as episode 9: indexes are visible via --show-files, selection via --select-file. This interface consistency makes this episode feel like tidying up what you've already learned.

#Remote Metalink and Base URI

Metalinks are often downloaded from a URL rather than read from disk. When a .meta4 file contains relative URLs, aria2 needs to know their reference point — that's where --metalink-base-uri comes in. For example, a metalink document containing <url>debian.iso</url> without a host can be completed with a base URI:

aria2c --metalink-base-uri=https://mirror1.example.com/pub/ \
  release.meta4

With a base URI, relative URLs inside the metalink resolve to absolute addresses and the download runs without editing the description file. Practical when metalinks are copied between directories or generated by a content management system.

#When to Use Metalink

When should you use Metalink instead of a plain input file? The main considerations are integrity guarantees and multi-protocol support:

• Need automatic checksums? Metalink carries hashes and piece checksums, so verification is fused into the download — the input file doesn't.
• Need a combined HTTP and torrent download? Metalink wraps both in one file; the input file only holds HTTP/FTP URLs.
• Want one file per entity? A single .meta4 is enough for one entity with many mirrors, tidier than dozens of URL lines.
• Keep it simple? For an ordinary list of files that happen to have many mirrors, the episode 6 input file remains the more concise choice.

In practice the two complement each other: the input file for large lists, Metalink for entities demanding reliability and multi-protocol.

#Closing

In episode 10 you understood Metalink as a single-file description format that summarizes many mirrors, checksums, and torrents; downloaded from .meta4 with mirror selection via --metalink-location and --metalink-preferred-protocol; enjoyed automatic checksum verification during the download; and combined HTTP with BitTorrent in one process.

The most important takeaway: Metalink turns reliability from "hopefully" into "guaranteed" — multiple sources make downloads resilient to server failures, and checksums catch corrupted data as early as possible.

In the next episode, episode 11, we tidy up the warehouse: directory and output file name management, name-conflict handling, and integrity verification of large files. See you then!