aria2: A Command-Line Downloader That Speaks HTTP, BitTorrent and Metalink at Once

The gap aria2 fills: one file, many sources, one process

Most download tools pick a protocol and stay there. A browser fetches over HTTP. A torrent client fetches over BitTorrent. If a release is published both as a direct HTTP file and as a torrent, you usually download it twice or choose one. aria2's stated design goal is to remove that choice. The README says it can download a file from HTTP(S)/FTP/SFTP and BitTorrent at the same time, and that data pulled over the HTTP side is uploaded to the BitTorrent swarm. That is the specific problem: aggregating every available source for a single file into one transfer, in one process, from a terminal. The audience follows from that. It is written for people running headless servers, build farms, seedboxes and shell scripts, not for someone who wants a download button in a window. The feature list is explicit about the interface: command-line only, with an RPC layer for control from other programs.

Segmented downloads, chunk checksums and the Metalink path

The core mechanism is segmented downloading. aria2 splits a file into pieces and fetches them in parallel, which is what lets it saturate a connection that a single TCP stream would leave idle. Metalink is where this becomes more than a speed trick. Metalink version 4 (RFC 5854) and version 3.0 are both supported across HTTP, FTP, SFTP and BitTorrent, and Metalink/HTTP (RFC 6249) is supported as well. A Metalink document carries multiple mirrors plus per-chunk checksums. The README states that aria2 uses those chunk checksums to validate data while downloading, in the same way BitTorrent validates pieces. So the data flow is: read the Metalink descriptor, pick sources, fetch chunks in parallel, verify each chunk against its hash as it arrives, and discard anything that fails. That last step is the part worth noting. A corrupted mirror does not silently poison the output file; the bad chunk is rejected. The README also notes that chunk checksum validation is a Metalink feature and that segmented downloading can be disabled in Metalink, which matters when a server punishes parallel range requests.

BitTorrent extensions and the WEB-Seeding detail

The BitTorrent side is not a minimal implementation. The feature list names the Fast extension, DHT, PEX, MSE/PSE, multi-tracker support, UDP trackers and Local Peer Discovery. WEB-Seeding is supported, and the README gives a concrete description of how aria2 approaches it: it requests a chunk larger than the piece size to reduce request overhead, and it supports pipelined requests with piece size. Those two sentences are the most technically specific in the document, and they describe a real trade-off. Larger requests mean fewer round trips, which helps on high-latency links, but they also mean more wasted work if a connection drops mid-request. The README does not quantify the benefit, and I have not measured it. What can be said is that the mechanism is documented rather than implied. Selective download in multi-file torrents and Metalink files is also listed, so you can pull one file out of a large torrent without taking the rest.

Building aria2: dependencies, configure flags and the C++11 requirement

This is a source-first project. The README's build section says the current source requires a C++11 aware compiler and that the codebase is being migrated from C++98/C++03 to C++11. The dependency table maps features to libraries rather than giving a single install line. HTTPS needs OSX, GnuTLS, OpenSSL or Windows TLS. SFTP needs libssh2. BitTorrent has no mandatory dependency, with libnettle plus libgmp, libgcrypt or OpenSSL as optional. Metalink and XML-RPC need libxml2 or Expat. gzip and deflate in HTTP need zlib. Async DNS needs c-ares. Firefox3 and Chromium cookie loading needs libsqlite3. The precedence rules are where builds go wrong. libxml2 wins over Expat unless you pass --without-libxml2. GnuTLS wins over OpenSSL unless you pass --without-gnutls --with-openssl. On macOS, OS-level TLS and checksum support are preferred unless you pass --without-appletls. On Windows, Schannel-based TLS is preferred unless you pass --without-wintls. For checksums, libnettle beats libgcrypt unless you pass --without-libnettle --with-libgcrypt, and if OpenSSL is selected over GnuTLS neither is used. If no optional checksum library is present, an internal implementation supporting only md5 and sha1 is used. You can drop protocol support entirely with --disable-bittorrent and --disable-metalink. To get the source: git clone https://github.com/aria2/aria2.git, which creates an aria2 directory in the current directory.

Control surfaces: JSON-RPC, XML-RPC and daemon mode

aria2 is not only a one-shot command. It exposes JSON-RPC over HTTP and WebSocket, and XML-RPC, and it can run as a daemon process. That combination is what makes it usable as a download backend behind another application: start the daemon, then drive it from a script or a service over the RPC interface. The WebSocket transport for JSON-RPC depends on libnettle, libgcrypt or OpenSSL, so a build configured without a crypto library will not have that path. The README does not describe RPC method names or payload shapes; those live in the online manual, which is published in English with Russian and Portuguese translations. If you are evaluating aria2 as an embedded download engine, the manual is the document you actually need, not the README. The README is a feature inventory and build guide.

Where aria2 is the wrong tool

The release history is the clearest limitation. The three most recent releases listed are 1.37.0 in November 2023, 1.36.0 in August 2021 and 1.35.0 in October 2019. The README describes an intended schedule of minor updates on the 15th of every month, with a feature and documentation freeze ten days earlier for translation teams, and patch releases between regular releases for security issues. The gap between 1.35.0 and 1.36.0 is nearly two years, and between 1.36.0 and 1.37.0 more than two. The stated schedule and the observed cadence do not match. For a tool that handles TLS and parses remote metadata, that matters. A second limitation is the interface itself: there is no GUI in this repository, and the README lists command-line as the first feature. If your users need a visual queue, a browser extension or a system tray icon, aria2 is a component you would have to wrap, not a product you hand over. Third, the crypto and TLS configuration is a genuine source of build variance. Two machines with the same aria2 version can behave differently on TLS depending on which library was picked up at configure time. That is not a bug, but it is a support burden. Finally, the disclaimer is blunt: the program comes with no warranty and you use it at your own risk.

How it compares to a browser download manager and to curl

The obvious alternative for scripted fetching is curl. curl is a transfer tool: it makes requests, follows redirects, handles auth and writes bytes to a file or stdout. It does not segment a single file across parallel connections by default, it has no BitTorrent support, and it does not parse Metalink descriptors to pick mirrors or verify chunks. aria2 does all three. The trade is scope. curl is a general-purpose HTTP client library and binary used inside countless other programs; aria2 is a downloader with a narrower job and a larger dependency surface for that job. If your task is "fetch this URL and pipe it somewhere", curl is the smaller answer. If your task is "fetch this 40 GB release from whichever of these twelve mirrors and this torrent is fastest, and tell me if any chunk is corrupt", aria2 is built for exactly that. Against a desktop BitTorrent client, the difference is the opposite direction: those give you a GUI, a queue and a scheduler, and they generally do not merge HTTP mirrors into the same transfer.

Licence and upgrade cost

aria2 is GPL-2.0. If you embed it in a distributed product, the GPL-2.0 obligations travel with it: source availability and the same-licence terms for derivative works. Linking against it from a proprietary application is the case to examine carefully with your own counsel; this article is not legal advice. On upgrade cost, the practical issue is that the project's own release schedule is monthly but the observed releases are years apart, so the version packaged by your distribution may be the version you run for a long time. Building from source means tracking the configure flags for libxml2 versus Expat, GnuTLS versus OpenSSL, and libnettle versus libgcrypt, because a rebuild on a differently provisioned machine can select a different library set and change TLS behaviour. The mitigation is to pin those flags explicitly in your build script rather than relying on precedence rules. That is a concrete step tied to this project's configure interface, and it is the one I would take before rolling aria2 out across more than a handful of machines.

Editorial conclusion

Adopt aria2 if you need a headless, scriptable downloader that can combine HTTP mirrors with a BitTorrent swarm and verify chunks through Metalink, and if you can accept GPL-2.0 obligations and a source build on most Linux distributions. Do not adopt it if you need a desktop GUI, a browser-integrated download manager, or a project with a fast release cadence. Before committing, verify that your platform's packaged version matches what you need, and check the configure flags for the crypto and Metalink libraries you intend to use.

Official sources

1. aria2/aria2 on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases