aria2 options reference
The options you actually use. Every entry maps an aria2c flag to its aria2.conf key, with an example. This is a curated companion to the official manual, which lists the complete set.
| Flag | aria2.conf key | What it does | Example |
|---|---|---|---|
-d | dir | Directory to save the downloaded file(s). | aria2c -d /downloads URL |
-o | out | Set the output file name. | aria2c -o file.iso URL |
-c | continue | Resume a partially downloaded file. | aria2c -c URL |
-i | input-file | Download every URI listed in a text file. | aria2c -i urls.txt |
-j | max-concurrent-downloads | Maximum number of downloads running at once. | aria2c -j 5 URL |
-Z | | Fetch all URIs in one operation (batch mode). | aria2c -Z URL1 URL2 |
--save-session | save-session | Write current downloads to a session file for later resume. | aria2c --save-session=aria.session URL |
--save-session-interval | save-session-interval | How often (seconds) to auto-save the session file. | --save-session-interval=60 |
--allow-overwrite | allow-overwrite | Overwrite an existing file instead of failing. | --allow-overwrite=true |
-x | max-connection-per-server | Connections per server (1–16). Higher speeds up large files. | aria2c -x 16 URL |
-s | split | Split the file into N pieces downloaded in parallel. | aria2c -s 16 URL |
-k | min-split-size | Minimum size of a split piece. | aria2c -k 1M URL |
-m | max-tries | Number of retries before giving up. | aria2c -m 5 URL |
--retry-wait | retry-wait | Seconds to wait between retries. | --retry-wait=5 |
-t | timeout | Connection timeout in seconds. | aria2c -t 60 URL |
--connect-timeout | connect-timeout | Timeout for establishing the connection. | --connect-timeout=30 |
--lowest-speed-limit | lowest-speed-limit | Abort if speed drops below this value. | --lowest-speed-limit=10K |
-U | user-agent | Override the HTTP User-Agent. | aria2c -U "Mozilla/5.0" URL |
--referer | referer | Send a Referer header. | --referer="https://example.com" |
--header | header | Add a custom HTTP header. | --header="Authorization: Bearer X" |
--load-cookies | load-cookies | Read cookies from a Netscape-format file. | --load-cookies=cookies.txt |
--check-certificate | check-certificate | Verify TLS certificates (disable only if you trust the source). | --check-certificate=false |
--ca-certificate | ca-certificate | Path to a CA certificate bundle. | --ca-certificate=/etc/ssl/certs/ca-certificates.crt |
-V | check-integrity | Verify chunk checksums (Metalink/BitTorrent). | aria2c -V URL |
--bt-tracker | bt-tracker | Comma-separated tracker list for torrents. | --bt-tracker="udp://tracker.opentrackr.org:1337/announce" |
--bt-max-peers | bt-max-peers | Maximum peers per torrent (0 = unlimited). | --bt-max-peers=128 |
--enable-dht | enable-dht | Enable the DHT network for trackerless torrents. | --enable-dht=true |
--bt-enable-lpd | bt-enable-lpd | Enable Local Peer Discovery. | --bt-enable-lpd=true |
--seed-ratio | seed-ratio | Stop seeding after this upload/download ratio (0 = seed forever). | --seed-ratio=1.0 |
--seed-time | seed-time | Minutes to seed after completion. | --seed-time=60 |
--bt-save-metadata | bt-save-metadata | Save torrent metadata from a magnet link. | --bt-save-metadata=true |
--bt-seed-unverified | bt-seed-unverified | Seed without verifying existing pieces first. | --bt-seed-unverified=true |
--enable-rpc | enable-rpc | Start the JSON-RPC/XML-RPC server. | --enable-rpc=true |
--rpc-listen-all | rpc-listen-all | Listen on all interfaces (keep local unless secured). | --rpc-listen-all=true |
--rpc-listen-port | rpc-listen-port | RPC port (default 6800). | --rpc-listen-port=6800 |
--rpc-secret | rpc-secret | Secret token required to use the RPC interface. | --rpc-secret=YOUR_SECRET |
--rpc-allow-origin-all | rpc-allow-origin-all | Allow cross-origin browser clients (Web UIs). | --rpc-allow-origin-all=true |
-D | daemon | Run as a background daemon. | aria2c -D --enable-rpc |
-l | log | Write the log to a file. | aria2c -l aria2.log URL |
--on-download-complete | on-download-complete | Command to run when a download finishes. | --on-download-complete=/path/hook.sh |
--on-download-error | on-download-error | Command to run when a download fails. | --on-download-error=/path/err.sh |
--all-proxy | all-proxy | HTTP proxy for all protocols (HTTP/HTTPS/FTP). SOCKS is not supported. | --all-proxy="http://127.0.0.1:8080" |
--http-proxy | http-proxy | Proxy for HTTP only. | --http-proxy="http://127.0.0.1:8080" |
--all-proxy-user | all-proxy-user | Username for proxy authentication. | --all-proxy-user=user |
--all-proxy-passwd | all-proxy-passwd | Password for proxy authentication. | --all-proxy-passwd=pass |
--no-proxy | no-proxy | Comma-separated hosts that bypass the proxy. | --no-proxy=localhost,127.0.0.1 |
--disable-ipv6 | disable-ipv6 | Disable IPv6. | --disable-ipv6=true |
--file-allocation | file-allocation | Pre-allocation mode: none, prealloc, trunc, falloc. | --file-allocation=falloc |
--disk-cache | disk-cache | Enable disk cache and set its size. | --disk-cache=64M |
--max-download-limit | max-download-limit | Per-download speed cap. | --max-download-limit=1M |
--max-overall-download-limit | max-overall-download-limit | Global download speed cap. | --max-overall-download-limit=5M |
--max-overall-upload-limit | max-overall-upload-limit | Global upload speed cap. | --max-overall-upload-limit=1M |
--remote-time | remote-time | Apply the server's timestamp to the file. | --remote-time=true |
--auto-file-renaming | auto-file-renaming | Rename instead of overwriting existing files. | --auto-file-renaming=true |
No option matches that keyword. Try “split”, “proxy”, or “seed”, or see the official manual.
Build a config from these options
Use the config generator to turn these settings into a ready-to-use aria2.conf, or read the full aria2 guide. Hitting an error? Try troubleshooting.