Does aria2 support resuming Metalink downloads?

This article examines the capabilities of the command-line download utility aria2 regarding the resumption of interrupted Metalink downloads. While aria2 natively supports resuming standard downloads and reads Metalink files to orchestrate multi-source transfers, its ability to resume a Metalink session depends heavily on how the download was initiated, the status of the local control file, and the configuration of the remote servers. Below, we break down how aria2 handles these files, the exact mechanisms for resuming them, and the specific technical limitations users may encounter.

Resuming Metalink Downloads in aria2

aria2 is highly capable of resuming downloads that utilize the Metalink XML format. When a Metalink file is loaded, aria2 parses the metadata to find alternative mirrors, file chunks, and cryptographic checksums. If a transfer is interrupted by a network drop or user cancellation, it can typically pick up right where it left off, provided certain conditions are met.

The Role of the Control File

To successfully resume any download, including those driven by a Metalink, aria2 relies on a control file with the extension .aria2.

• State Preservation: This control file saves the state of the download, tracking which chunks of the file have been successfully downloaded and verified.
• Command Persistence: If you stop aria2 and restart the exact same command pointing to the original Metalink file in the same directory, aria2 will detect the .aria2 file and the partially downloaded target file, allowing it to resume the process seamlessly.

Multi-Source Failover

One of the key strengths of using Metalinks with aria2 is its ability to resume a download from a entirely different mirror if the original server goes offline during the interruption. Because the Metalink provides a list of identical cryptographic sources, aria2 can use the chunk data stored in the .aria2 control file to continue downloading missing pieces from any available host listed in the XML.

Specific Limitations and Constraints

While resumption is supported, users must navigate several technical limitations that can cause the resume process to fail, forcing the download to restart from scratch.

Missing or Corrupted Control Files

If the .aria2 control file is deleted, corrupted, or if aria2 is explicitly told to ignore it (via the --allow-overwrite=true flag without proper caution), aria2 loses the map of which chunks have been downloaded. Without this file, aria2 cannot verify the integrity of the partial download on disk and will restart the download from 0%.

Server-Side Restraints

Even though aria2 supports resumption, the remote servers hosting the files must also support it.

• Range Requests: The hosting servers must support HTTP Range requests or FTP resume capabilities. If a mirror listed in the Metalink does not support chunked or partial content requests, aria2 cannot resume from that specific source.
• Dynamic Links: If the Metalink contains URLs that expire quickly or rely on temporary session tokens, attempting to resume the download at a later time will result in “403 Forbidden” or “404 Not Found” errors from the host servers.

Mismatched File Allocation

If you change allocation settings between sessions (such as switching from --file-allocation=prealloc to --file-allocation=none), or if the local file size on disk does not match what the .aria2 control file expects, aria2 may flag the download as inconsistent and refuse to resume to prevent data corruption.