Learn Aria2 - BitTorrent Download

#Introduction

The last six episodes worked on a client-server pattern: one file on one server, with the connection split into several segments. BitTorrent changes the rules. There's no single central server serving the file — the file is split into small pieces, and everyone downloading simultaneously shares the pieces they already have with others. The more participants, the faster the download. This episode takes you into mastering aria2's BitTorrent mode: from torrent files and magnet links, to seeding behavior, DHT, and peer discovery.

Why does this matter? Because large software distribution — Linux ISOs, dataset packages, game patches — almost always offers torrents as a reliable route. Understanding how aria2 behaves as a peer in a torrent network lets you use that route professionally.

#Two Entry Points: Torrent Files and Magnet Links

BitTorrent separates two things that ordinary downloads keep together: metadata and content. The metadata (infohash, piece size, file list, checksum of each piece) can be provided as a .torrent file or as a magnet link that only contains a hash — like a file's account number.

aria2c -d /srv/torrents ubuntu-24.04-desktop-amd64.iso.torrent

aria2c -d /srv/torrents "magnet:?xt=urn:btih:3b4c8a0f1e2d9c7b6a5f4e3d2c1b0a9f8e7d6c5b"

A magnet link only contains the infohash after urn:btih:. The metadata isn't there yet — aria2 must fetch it from other peers over the network first. From a user's point of view both are a single command, but the mechanism behind them differs. The directory structure inside the torrent is preserved relative to -d.

#Seeding After Download

A fundamental difference from HTTP: after the download finishes, aria2 doesn't just stop. As a swarm member, it now becomes a seeder — sending the pieces it has to other peers. That's great for the community, but not always desirable for a server with limited bandwidth.

When seeding stops is governed by --seed-time (minutes) and --seed-ratio (upload-to-download ratio, default 1.0). If both are given, seeding ends when either condition is met.

aria2c -d /srv/torrents --seed-time=60 ubuntu-24.04-desktop-amd64.iso.torrent

The command above stops seeding after one hour. To stop seeding entirely, set --seed-time=0 — download complete means process complete, no upload at all. This value must be considered before running many torrents on a machine with an upload quota.

#DHT and Peer Discovery

To find peers, classic BitTorrent uses a tracker — a server that records who's currently downloading the same torrent. But a tracker is a single point of failure: one server down, peer discovery down. That's where DHT (Distributed Hash Table) comes in — peers find other peers without a central server, like an acquaintance network spreading from one node to the next. The more nodes in the network, the more complete the map of friends.

aria2 enables IPv4 DHT by default (--enable-dht). A few settings worth knowing:

• --dht-listen-port — the UDP port for DHT (default 6881-6999).
• --listen-port — the TCP port for incoming peer connections (default 6881-6999).
• --enable-dht6 — turns on IPv6 DHT.
• --bt-enable-lpd — Local Peer Discovery, finds peers on the same local network.
• --enable-peer-exchange — PEX, exchanging peer lists directly (enabled by default).
• --bt-tracker — adds external trackers per download, useful when the torrent's built-in trackers are down or slow.
• --dht-entry-point — a public node for "introducing yourself" to the DHT network the first time, for example router.bittorrent.com:6881.

aria2c -d /srv/torrents --listen-port=6881-6999 \
  --dht-listen-port=6881-6999 --enable-dht=true \
  --dht-entry-point=router.bittorrent.com:6881 \
  "magnet:?xt=urn:btih:3b4c8a0f1e2d9c7b6a5f4e3d2c1b0a9f8e7d6c5b"

The DHT routing table is stored in ~/.aria2/dht.dat, so after one bootstrap, later sessions already know where to look. To let peers reach your machine, make sure ports 6881-6999 (TCP and UDP) are open in the firewall and forwarded through NAT if needed — this is crucial for smooth peer connections.

#Fetching Metadata Without Content

Sometimes you only need the .torrent file itself, not its contents — for example for auditing or sharing with another machine that isn't connected to the internet. Two options work as a pair:

• --bt-metadata-only=true — downloads only the metadata, never touches content.
• --bt-save-metadata=true — saves the metadata as a .torrent file in the download directory, named by the infohash in hex.

aria2c --bt-metadata-only=true --bt-save-metadata=true \
  "magnet:?xt=urn:btih:3b4c8a0f1e2d9c7b6a5f4e3d2c1b0a9f8e7d6c5b"

When it finishes, you'll see a 3b4c8a0f...torrent file in your working directory. That's the file to share or move to another machine for a normal download. With --bt-load-saved-metadata=true, a magnet link in a later session can directly use the saved metadata without hunting for it in the DHT again.

#Selective Download

A torrent can hold dozens of files while you only need some. First inspect its contents with --show-files, then select by index with --select-file.

aria2c --show-files dataset-huge.torrent

The output lists files with index numbers starting at one. To download only files one and three:

aria2c -d /srv/dataset --select-file=1,3 dataset-huge.torrent

Indexes also accept ranges (1-5) and combinations (1-5,8,9). One small note: because a piece can hold parts of several files at once, nearby files technically get partially downloaded too — that's normal BitTorrent behavior, not a bug.

#Combining Torrents with HTTP Sources

One often underrated capability: aria2 can download a single file from both a torrent and ordinary HTTP/FTP URLs simultaneously. Give both in one command — the torrent determines structure and checksums, while the URL acts as an additional source.

aria2c -d /srv/torrents \
  https://mirror.example.com/app-2026.08.iso \
  app-2026.08.iso.torrent

Pieces already obtained over HTTP are uploaded to the swarm, and pieces from peers add speed. Because every piece is guaranteed by the torrent's checksum, there's no corruption risk even though data comes from two different directions. This is practical when you have HTTP access to your own server but want the swarm to help with the rest.

This behavior depends on --follow-torrent (enabled by default). When a .torrent file is downloaded — including when the file itself was an HTTP download — aria2 automatically parses it into a download. If you only want to save the .torrent file without processing it, set --follow-torrent=false.

#Closing

In episode 9 you entered the world of BitTorrent: downloading from .torrent files and magnet links, controlling when seeding stops with --seed-time, understanding DHT and peer discovery along with the port settings, fetching metadata only via --bt-metadata-only, and selecting specific files with --select-file.

The most important takeaway: in BitTorrent, you're not a passive client — you're part of the network. Port settings, DHT, and seeding determine how well you connect with the swarm, and how fairly you give back.

In the next episode, episode 10, we combine everything: Metalink — a single file that holds HTTP mirrors, checksums, and torrents all at once. See you then!