How to download from multiple sources with aria2?

aria2 can pull a single file from multiple parallel sources simultaneously. Use: aria2c -x 16 -s 16 http://mirror1.example.com/file.iso http://mirror2.example.com/file.iso. aria2 will download chunks from both URLs at the same time.

What is the aria2 JSON-RPC API and how do I use it?

aria2's JSON-RPC API is an HTTP server running on port 6800 that lets you add, pause, resume, and monitor downloads programmatically. Start it with: aria2c --enable-rpc --rpc-listen-all --rpc-secret=TOKEN. Then call methods like aria2.addUri via curl or any HTTP client.

How do I configure aria2 to save-session and resume after reboot?

Add to aria2.conf: save-session=~/.aria2/aria2.session and input-file=~/.aria2/aria2.session and save-session-interval=60. aria2 will periodically save all active downloads to the session file and automatically load them on next start.

What does file-allocation=falloc do in aria2?

The falloc mode tells the OS kernel to pre-allocate disk space for the entire file before downloading begins. This prevents filesystem fragmentation during parallel chunk downloads, which is critical for performance on HDDs and NVMe drives when downloading large files (50GB+).

Docs / Setup & Basics / Build & Install

Building & Installation - The Ultra Fast Download Utility

Q: How to build aria2 from source on Linux?

Install dependencies with: sudo apt install libgnutls28-dev nettle-dev libgmp-dev libssh2-1-dev libc-ares-dev libxml2-dev zlib1g-dev libsqlite3-dev pkg-config. Then run: git clone https://github.com/aria2/aria2.git && cd aria2 && autoreconf -i && ./configure && make

aria2 is a free, open-source, multi-protocol CLI download tool written in C++ that supports HTTP, HTTPS, FTP, SFTP, BitTorrent, and Metalink. It downloads files up to 16× faster than wget or curl by opening up to 16 parallel connections simultaneously, while using only 4–9 MiB of RAM. Available for Windows, macOS, Linux, and Android — no GUI required.

Use this documentation to master installation on Windows, Linux, and macOS, configure advanced protocol engines, and integrate aria2 into your own automation pipelines.

bash

# 1. Install dependencies (Debian/Ubuntu) $sudo apt install libgnutls28-dev nettle-dev libgmp-dev libssh2-1-dev libc-ares-dev libxml2-dev zlib1g-dev libsqlite3-dev pkg-config # 2. Clone and Build $git clone https://github.com/aria2/aria2.git $cd aria2 $autoreconf -i $./configure $make # OPTIONAL: Build a single static binary for portability $./configure ARIA2_STATIC=yes

Cross-compiling: aria2 uses mingw-config and android-config wrappers for generating Windows (.exe) and Android binaries using MinGW and NDK toolchains respectively.

Docs / Setup & Basics / HTTP & FTP Config

Basic HTTP & FTP Configuration

aria2 handles typical HTTP/FTP downloads brilliantly out of the box, but its real power lies in Protocol Hybridization. It can download a file from HTTP/FTP/SFTP and BitTorrent simultaneously, uploading data from the direct sources to the BitTorrent swarm to maximize efficiency.

Note: aria2 is purely a command-line program and RPC backend. If you use -x 16 to open 16 connections, some servers may temporarily rate-limit your IP. Always tune your concurrent limits responsibly.

cli

# Standard execution $aria2c http://example.org/mylinux.iso # Pull from 16 connections simultaneously, splitting the file into 16 chunks $aria2c -x 16 -s 16 http://example.org/mylinux.iso # Parameterized URI: Download file01.iso through file05.iso in one go $aria2c "http://example.org/file{01,02,03,04,05}.iso" # Set custom User-Agent and Referer headers $aria2c --user-agent="MyBrowser/1.0" --referer="http://google.com" http://file.com/d.zip

Docs / Setup & Basics / Quickstart & CLI Commands

Batch Automations

For scraping, mirror synchronization, and batch operations, you can feed aria2 a raw text file containing thousands of URLs. It will aggressively download them in parallel using the -i (input) parameter.

cli

# Read all targets from a formatted text document $aria2c -i huge_list.txt --max-concurrent-downloads=5 # Parameterized bash expansion downloading $aria2c -Z -P "http://host/image[000-100].png"

Docs / Deep Dive / BitTorrent

BitTorrent Deep Dive

aria2 possesses fully-fledged BitTorrent client capabilities integrated directly into its core engine. It supports DHT routing tables, Local Peer Discovery (LPD), and Magnet URI resolution natively.

Note: aria2 is one of the only clients that inherently supports BitTorrent WebSeeding. You can link a standard HTTP mirror securely into a P2P swarm simultaneously!

cli

# Download via .torrent file using 55 max peers $aria2c --bt-max-peers=55 ubuntu.torrent # Download via Magnet URI cleanly $aria2c "magnet:?xt=urn:btih:248D0A1CD...&dn=ubuntu" # Stop seeding automatically when ratio hits 1.5 $aria2c --seed-ratio=1.5 ubuntu.torrent

Docs / Deep Dive / Metalink

Metalink Support

Metalinks are XML files containing URI lists, checksums, and metadata. aria2 uses these to automatically find the fastest mirror and verify file integrity simultaneously.

cli

# Download via a local metalink file $aria2c -M download.metalink # Download only specific files from a metalink (1, 3, and 5) $aria2c --select-file=1,3,5 http://example.org/files.metalink

Docs / Deep Dive / Auth & Cloud

Auth & Cloud Bypass (Cookies)

Many modern mirror sites require a login session to access premium or private bandwidth limits. You can export a cookies.txt file straight from Google Chrome or Firefox and plug it into aria2 to instantly authorize headless downloads.

cli

# Impersonate your active browser session directly $aria2c --load-cookies=cookies.txt https://host/premium-file.rar # Standard HTTP Basic Auth $aria2c --http-user="admin" --http-passwd="password" http://...

Docs / Advanced / Resuming

Resuming & Recovery

Unlike wget, aria2 has highly robust file-recovery capabilities. If your internet disconnects or your power fails during a huge file transfer, aria2 can seamlessly resume data verification using the -c / --continue flag.

cli

# Resume a broken download $aria2c -c http://example.org/mylinux.iso

If you don't use -c and the file already exists, aria2 defaults to auto-renaming the new download to mylinux.1.iso to prevent accidental overwrites.

Docs / Advanced / Throttling

Bandwidth Throttling

Prevent aria2 from monopolizing your home network when downloading in the background by setting strict throttle limits. Limits can be applied globally to the entire daemon, or individually per task.

cli

# Restrict the entire aria2 daemon to 2 megabytes per second $aria2c --max-overall-download-limit=2M -i urls.txt # Restrict EACH specific task to 500 kilobytes per second $aria2c --max-download-limit=500K http://example.org/hq.mp4

Docs / Advanced / Disk I/O

Disk Allocation & High-Speed I/O

When downloading huge 50GB++ files via 16 parallel split connections, mechanical HDD disks (and basic SSDs) experience colossal filesystem fragmentation resulting in slowdowns.

Aria2's falloc engine instantly commands the operating system to pre-map block allocation directly at the kernel level before the download even begins.

cli

# Pre-allocate blocks (Supported on Ext4, XFS, Btrfs, and NTFS) $aria2c --file-allocation=falloc http://example.org/50G.iso

Docs / Advanced / Checksums

Checksums & Integrity

Ensure your downloads haven't been corrupted or tampered with by forcing aria2 to verify hash sums during or after the transfer.

cli

# Verify MD5/SHA-256 hash immediately upon completion $aria2c --checksum=sha-256=HASH_STRING http://example.org/file.zip # Deep repair: Check existing file pieces and only download the broken ones $aria2c --check-integrity=true ubuntu.torrent

Docs / Networking / IPv6

Advanced Networking & IPv6

Fine-tune how aria2 binds to your local hardware interfaces, especially useful for multi-homed servers or VPN setups.

cli

# Disable IPv6 if your network/ISP doesn't support it $aria2c --disable-ipv6=true http://example.org/file # Bind all traffic to a specific local interface (e.g., eth1) $aria2c --interface=eth1 http://example.org/file # Happy Eyeballs: Optimized IPv6/IPv4 fallback algorithm is used by default.

Docs / Networking / Proxy

Proxy Configurations

aria2 natively supports HTTP and SOCKS5 proxy servers, SSL verification overriding, and explicit IPv6 bindings.

cli

# Force traffic cleanly over a SOCKS5 payload $aria2c --all-proxy="socks5://127.0.0.1:1080" http://example.org/ # Bypass untrusted SSL server certificate halts natively $aria2c --check-certificate=false https://raw-server.net/

Docs / Networking / Security

Security & Encryption

For BitTorrent transfers, you can force encryption to bypass ISP snooping or throttling. You can also define strict SSL certificate requirements for secure HTTP links.

cli

# Require BitTorrent encryption (refuse non-encrypted peers) $aria2c --bt-require-encryption=true ubuntu.torrent # Use a specific CA certificate to verify the server $aria2c --ca-certificate=/path/to/ca.pem https://secure-server.com/

Docs / Automation / Daemon

Daemon Services

Run aria2 completely decoupled in the background. Essential for building VPS, Seedbox, and headless server environments.

cli

# Run as a background daemon process $aria2c --daemon=true --enable-rpc=true --conf-path=/etc/aria2.conf

Docs / Automation / RPC

RPC Subsystems (Remote Control)

The JSON-RPC interface allows you to send commands to aria2 from remote servers, mobile apps, or web GUIs like AriaNg.

cli

# Start the RPC Server securely on port 6800 $aria2c --enable-rpc --rpc-listen-all --rpc-secret=mySecretToken # Simple curl call to add a download via RPC $curl -X POST -d '{"jsonrpc":"2.0","id":"q","method":"aria2.addUri","params":["token:mySecretToken",["URL"]]}' http://localhost:6800/jsonrpc

Method	Description
`aria2.addUri`	Adds a new HTTP/FTP/SFTP download.
`aria2.addTorrent`	Adds a BitTorrent download by uploading a .torrent file.
`aria2.tellStatus`	Returns progress/status for a specific GID.
`aria2.pauseAll`	Pauses all active downloads instantly.
`aria2.getOption`	Retrieves config flags for a specific GID.

Docs / Automation / Hooks

Event Hooks & Scripting

Trigger automated tasks using Aria2's built-in event listeners. You can parse variables like File Paths and GIDs into external bash environments.

cli

# Trigger "unzip.sh" immediately upon successful 100% completion $aria2c --on-download-complete=/opt/scripts/unzip.sh http://...

Docs / Configuration / aria2.conf

The Perfect `aria2.conf`

Define rigid engine mechanics in your static configuration file (typically ~/.aria2/aria2.conf) to avoid manual flags.

~/.aria2/aria2.conf

# --- Performance Tuning --- max-connection-per-server=16 split=16 file-allocation=falloc # --- RPC Server --- enable-rpc=true rpc-secret=YOUR_KEY # --- State --- save-session=~/.aria2/aria2.session input-file=~/.aria2/aria2.session

Docs / Configuration / Environment

Environment Variables

aria2 natively parses standard operating system proxy variables from your terminal profile.

Variable	Description
`http_proxy`	Default proxy for HTTP requests.
`https_proxy`	Default proxy for HTTPS requests.
`all_proxy`	Global proxy server.
`no_proxy`	Domains to bypass proxy routing.

Docs / Reference / Progress

Understanding Console Progress

Real-time snapshot strings provided by the console engine.

cli

[#GID 123MB/456MB(27%) CN:16 DL:5.2MB UL:12KB ETA:1m45s]

GID: Task unique identifier.
CN: Active connections.
DL / UL: Current speeds.
ETA: Estimated time remaining.

Docs / Reference / Files

Technical Files & Formats

Binary layouts and state files used under the hood.

File	Purpose
`dht.dat`	Stores the DHT routing table (Binary).
`.netrc`	Automatic HTTP/FTP credentials.
`aria2.session`	Pause/resume session state.
`*.aria2`	v1 Binary control files (Big Endian).

tips

Netrc Format: machine example.com login user password password

Docs / Reference / Status Codes

Exit Status Codes

Parse $? in scripts to handle failures gracefully.

Code	Meaning
0	Success
1	Unknown Error
3	404 Not Found
9	Disk Full

Docs / Reference / Power User

Power User Tips & Units