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 / Einrichtung & Grundlagen / Bauen & Installation

aria2-Dokumentation: Installation, Konfiguration & Automatisierung

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 ist ein freies, quelloffenes, multiprotokollfähiges CLI-Download-Tool in C++, das HTTP, HTTPS, FTP, SFTP, BitTorrent und Metalink unterstützt. Auf Servern, die die Geschwindigkeit pro Verbindung begrenzen, ist es oft um ein Mehrfaches schneller als wget oder curl, weil es bis zu 16 parallele Verbindungen pro Server öffnet und dabei nur 4–9 MiB RAM benötigt. Verfügbar für Windows, macOS, Linux und Android – ganz ohne GUI.

Nutzen Sie diese Dokumentation, um die Installation unter Windows, Linux und macOS zu meistern, erweiterte Protokoll-Engines zu konfigurieren und aria2 in Ihre eigenen Automatisierungspipelines zu integrieren.

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-Kompilierung: aria2 verwendet die Wrapper mingw-config und android-config zum Erzeugen von Windows- (.exe) und Android-Binärdateien mit den MinGW- bzw. NDK-Toolchains.

Docs / Einrichtung & Grundlagen / HTTP- & FTP-Konfiguration

Grundlegende HTTP- & FTP-Konfiguration

aria2 bewältigt typische HTTP-/FTP-Downloads bereits out of the box hervorragend, doch seine wahre Stärke liegt in der Protokoll-Hybridisierung. Es kann eine Datei über HTTP/FTP/SFTP und BitTorrent gleichzeitig herunterladen und dabei Daten aus den direkten Quellen in den BitTorrent-Schwarm hochladen, um die Effizienz zu maximieren.

Hinweis: aria2 ist ausschließlich ein Kommandozeilenprogramm und RPC-Backend. Wenn Sie mit -x 16 16 Verbindungen öffnen, drosseln manche Server Ihre IP temporär. Passen Sie parallele Limits daher stets verantwortungsvoll an.

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 / Einrichtung & Grundlagen / Schnellstart & CLI-Befehle

Batch-Automatisierungen

Für Scraping, Mirror-Synchronisierung und Stapelverarbeitung können Sie aria2 eine reine Textdatei mit Tausenden von URLs übergeben. Es lädt diese dann aggressiv parallel herunter – über den Parameter -i (Eingabe).

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 / Vertiefung / BitTorrent

BitTorrent im Detail

aria2 verfügt über vollwertige BitTorrent-Client-Funktionen, die direkt in seine Kern-Engine integriert sind. Es unterstützt nativ DHT-Routing-Tabellen, Local Peer Discovery (LPD) und die Auflösung von Magnet-URIs.

Hinweis: aria2 ist einer der wenigen Clients, die BitTorrent-WebSeeding von Haus aus unterstützen. Sie können einen Standard-HTTP-Mirror gleichzeitig sicher in einen P2P-Schwarm einbinden!

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 / Vertiefung / Metalink

Metalink-Unterstützung

Metalinks sind XML-Dateien mit URI-Listen, Prüfsummen und Metadaten. aria2 nutzt sie, um automatisch den schnellsten Mirror zu finden und gleichzeitig die Dateiintegrität zu prüfen.

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 / Vertiefung / Auth & Cloud

Auth- & Cloud-Umgehung (Cookies)

Viele moderne Mirror-Seiten erfordern eine Anmeldesitzung, um auf Premium- oder private Bandbreitenlimits zuzugreifen. Sie können eine Datei cookies.txt direkt aus Google Chrome oder Firefox exportieren und in aria2 einbinden, um Headless-Downloads sofort zu autorisieren.

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 / Erweitert / Fortsetzen

Fortsetzen & Wiederherstellung

Im Gegensatz zu wget verfügt aria2 über äußerst robuste Datei-Wiederherstellungsfunktionen. Wenn Ihre Internetverbindung abbricht oder der Strom während einer großen Dateiübertragung ausfällt, kann aria2 die Datenprüfung mit dem Flag -c / --continue nahtlos fortsetzen.

cli

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

Wenn Sie -c nicht verwenden und die Datei bereits existiert, benennt aria2 den neuen Download standardmäßig automatisch in mylinux.1.iso um, um versehentliches Überschreiben zu verhindern.

Docs / Erweitert / Drosselung

Bandbreitendrosselung

Verhindern Sie, dass aria2 beim Herunterladen im Hintergrund Ihr Heimnetzwerk monopolisiert, indem Sie strikte Drosselungslimits setzen. Limits können global für den gesamten Daemon oder individuell pro Aufgabe gelten.

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 / Erweitert / Festplatten-I/O

Festplatten-Allokation & Hochgeschwindigkeits-I/O

Beim Herunterladen riesiger 50-GB+-Dateien über 16 parallele Split-Verbindungen kommt es bei mechanischen HDD-Festplatten (und einfachen SSDs) zu enormer Dateisystemfragmentierung mit entsprechenden Verlangsamungen.

Die falloc-Engine von aria2 weist das Betriebssystem an, die Blockallokation direkt auf Kernel-Ebene vorzuzuordnen – noch bevor der Download überhaupt beginnt.

cli

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

Docs / Erweitert / Prüfsummen

Prüfsummen & Integrität

Stellen Sie sicher, dass Ihre Downloads weder beschädigt noch manipuliert wurden, indem Sie aria2 zwingen, Hashsummen während oder nach der Übertragung zu prüfen.

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 / Netzwerk / IPv6

Erweitertes Netzwerk & IPv6

Feinabstimmung, wie sich aria2 an Ihre lokalen Hardware-Schnittstellen bindet – besonders nützlich für Multi-Homed-Server oder 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 / Netzwerk / Proxy

Proxy-Konfigurationen

aria2 unterstützt HTTP-Proxys (HTTPS per CONNECT), das Überschreiben der SSL-Prüfung sowie explizite IPv6-Bindungen. SOCKS-Proxys werden nicht unterstützt – nutzen Sie für einen SOCKS5-Tunnel eine HTTP-zu-SOCKS-Brücke wie privoxy oder gost.

cli

# Route downloads through an HTTP proxy (aria2 has no SOCKS support) $aria2c --all-proxy="http://127.0.0.1:8080" http://example.org/ # Bypass untrusted SSL server certificate halts natively $aria2c --check-certificate=false https://raw-server.net/

Docs / Netzwerk / Sicherheit

Sicherheit & Verschlüsselung

Für BitTorrent-Übertragungen können Sie Verschlüsselung erzwingen, um ISP-Überwachung oder -Drosselung zu umgehen. Sie können außerdem strikte SSL-Zertifikatsanforderungen für sichere HTTP-Verbindungen festlegen.

cli

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

Docs / Automatisierung / Daemon

Daemon-Dienste

Betreiben Sie aria2 vollständig entkoppelt im Hintergrund. Unverzichtbar für VPS-, Seedbox- und Headless-Server-Umgebungen.

cli

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

Tipp: Wenn Sie Hintergrund-Downloads lieber interaktiv verwalten möchten, ohne einen Daemon-Dienst auszuführen, können Sie aria2c in einer abgetrennten tmux-Sitzung ausführen.

Docs / Automatisierung / RPC

RPC-Subsysteme (Fernsteuerung)

Über die JSON-RPC-Schnittstelle können Sie Befehle von entfernten Servern, mobilen Apps oder Web-GUIs wie AriaNg an aria2 senden.

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

Methode	Beschreibung
`aria2.addUri`	Fügt einen neuen HTTP-/FTP-/SFTP-Download hinzu.
`aria2.addTorrent`	Fügt einen BitTorrent-Download durch Hochladen einer .torrent-Datei hinzu.
`aria2.tellStatus`	Gibt Fortschritt/Status für eine bestimmte GID zurück.
`aria2.pauseAll`	Hält alle aktiven Downloads sofort an.
`aria2.getOption`	Ruft Konfigurations-Flags für eine bestimmte GID ab.

Docs / Automatisierung / Hooks

Event-Hooks & Skripting

Lösen Sie automatisierte Aufgaben mit den eingebauten Event-Listenern von aria2 aus. Sie können Variablen wie Dateipfade und GIDs in externe Bash-Umgebungen übergeben.

cli

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

Docs / Konfiguration / aria2.conf

Die perfekte `aria2.conf`

Definieren Sie starre Engine-Mechaniken in Ihrer statischen Konfigurationsdatei (typischerweise ~/.aria2/aria2.conf), um manuelle Flags zu vermeiden.

~/.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 / Konfiguration / Umgebung

Umgebungsvariablen

aria2 liest standardmäßig die Proxy-Variablen des Betriebssystems aus Ihrem Terminal-Profil.

Variable	Beschreibung
`http_proxy`	Standard-Proxy für HTTP-Anfragen.
`https_proxy`	Standard-Proxy für HTTPS-Anfragen.
`all_proxy`	Globaler Proxyserver.
`no_proxy`	Domänen, die das Proxy-Routing umgehen.

Docs / Referenz / Fortschritt

Konsolenfortschritt verstehen

Echtzeit-Snapshot-Zeichenketten der Konsolen-Engine.

cli

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

GID: Eindeutige Aufgabenkennung.
CN: Aktive Verbindungen.
DL / UL: Aktuelle Geschwindigkeiten.
ETA: Geschätzte Restzeit.

Docs / Referenz / Dateien

Technische Dateien & Formate

Binäre Layouts und Statusdateien, die unter der Haube verwendet werden.

Datei	Zweck
`dht.dat`	Speichert die DHT-Routing-Tabelle (binär).
`.netrc`	Automatische HTTP-/FTP-Zugangsdaten.
`aria2.session`	Status der angehaltenen/fortgesetzten Sitzung.
`*.aria2`	Binäre v1-Steuerdateien (Big Endian).

tips

Netrc Format: machine example.com login user password password

Docs / Referenz / Statuscodes

Exit-Statuscodes

Werten Sie $? in Skripten aus, um Fehler elegant zu behandeln.

Code	Bedeutung
0	Erfolg
1	Unbekannter Fehler
3	404 Nicht gefunden
9	Festplatte voll

Docs / Referenz / Power-User

Power-User-Tipps & Einheiten