aria2 User Guide

aria2 is a lightweight, multi-protocol, multi-source command-line download utility. It downloads a single file from HTTP(S), FTP, SFTP, BitTorrent, and Metalink — and can pull from several of those sources at the same time to saturate your bandwidth. The program installs as a single binary called aria2c.

This guide shows you how to install aria2, run your first download, and accomplish the everyday tasks you'll actually use it for. Deep configuration reference, the complete RPC API, build internals, and architecture live in the companion Admin Guide.

Note

aria2 is a command-line program. There is no built-in graphical interface. aria2 does, however, expose a JSON-RPC/XML-RPC interface that many third-party web and desktop front-ends build on. Driving aria2 over RPC is covered in the Admin Guide.

1. Quick Start

Once aria2 is installed (see Installation), downloading a file is a single command:

aria2c "https://example.org/file.zip"

[#2089b0 400.0KiB/33.2MiB(1%) CN:1 DL:115.7KiB ETA:4m51s]

That's it. The file lands in your current directory. A few of the most common variations:

Faster download (multiple connections)

aria2c -x 16 -s 16 "https://example.org/file.zip"

Download a torrent

aria2c "file.torrent"

Download a magnet link

aria2c "magnet:?xt=urn:btih:248D0A1CD08284299DE78D5C1ED359BB46717D8C&dn=aria2"

Download a list of URLs

aria2c -i urls.txt

Tip

Always wrap URLs and magnet links in single (') or double (") quotes. Magnet URIs and many HTTP URLs contain &, ?, and other characters that your shell will otherwise interpret.

To stop a download, press Ctrl-C. To resume it later, run the exact same command in the same directory — aria2 picks up where it left off using its control file (see Resuming Downloads).

2. Requirements

aria2 is distributed as a single self-contained executable. To simply run it you need:

Which protocols and features your particular aria2c binary supports depends on which optional libraries it was compiled against. Check what your build supports:

aria2c -v

aria2 version 1.37.0
...
Enabled Features:
Async DNS, BitTorrent, Firefox3 Cookie, GZip, HTTPS, Message Digest, Metalink, XML-RPC

Important

If a feature you need (for example BitTorrent, Metalink, HTTPS, or Firefox3/Chromium cookie loading) is missing from the Enabled Features line, your binary was built without the supporting library. Install a fuller build or compile aria2 yourself — see the Admin Guide's build chapter.

The current documented release is aria2 1.37.0.

3. Installation

aria2 ships in nearly every operating system's package repository. Use your package manager whenever possible — it's the simplest route and keeps aria2 updated alongside the rest of your system.

Debian / Ubuntu

sudo apt update
sudo apt install aria2

Fedora / RHEL

sudo dnf install aria2

Arch Linux

sudo pacman -S aria2

macOS (Homebrew)

brew install aria2

Windows

Download the official Windows build from the aria2 releases page, unzip it, and run aria2c.exe from a terminal (Command Prompt or PowerShell).

Verify the install:

aria2c --version

aria2 version 1.37.0
Copyright (C) 2006, 2019 Tatsuhiro Tsujikawa
...

Note

Distribution packages sometimes lag behind the latest aria2 release and may be compiled with a reduced feature set. If you need the newest version or a specific feature, build from source (covered in the Admin Guide) or use the official binaries.

If you need a self-contained, statically linked binary (no external shared-library dependencies), that is a build-time choice (ARIA2_STATIC=yes) — see the Admin Guide.

4. How aria2 Thinks (Just Enough to Be Productive)

A few concepts will make every later section clearer. This is the practical minimum; the full model is in the Admin Guide.

Download item vs. connections. aria2 separates how many files it downloads at once from how many connections it uses per file:

• -j, --max-concurrent-downloads — how many separate downloads run in parallel (default 5).
• -s, --split — how many connections a single file is split across (default 5).
• -x, --max-connection-per-server — cap on connections to one server for one download (default 1).
• -k, --min-split-size — aria2 won't split a byte range smaller than 2×SIZE (default 20M).

Tip

To make one big file download fast from a single host, raise both -x and -s, e.g. -x 16 -s 16. Raising -s alone won't help if -x keeps you to one connection per server.

Control file (.aria2). While downloading file.zip, aria2 keeps file.zip.aria2 next to it to track progress. This is what makes resume possible. It's deleted automatically when the download completes.

GID. Every download gets a 16-character hex GID (e.g. 2089b05ecca3d829). You'll see its first 6 characters in the console readout (#2089b0) and you use it to manage downloads over RPC.

Reading the console line:

[#2089b0 400.0KiB/33.2MiB(1%) CN:1 DL:115.7KiB ETA:4m51s]

5. Everyday HTTP / FTP Downloads

This is what most people use aria2 for. Each task below is a recipe you can copy.

5.1 Download a single file

aria2c "https://host/file.zip"

Choose where it goes and what it's called:

aria2c -d /downloads -o myfile.zip "https://host/file.zip"

• -d, --dir — directory to save into.
• -o, --out — output file name (always relative to --dir).

5.2 Download faster with multiple connections

aria2c -x 16 -s 16 -k 1M "https://host/bigfile.iso"

This opens up to 16 connections to the server and splits the file into 1 MiB-aligned segments.

Warning

More connections is not always better. Many servers throttle or reject clients that open too many parallel connections, and some count it as abuse. Start around -x 4 to -x 8 and increase only if the server tolerates it.

5.3 Download from several mirrors at once

If the same file is available from multiple servers, list them all — aria2 downloads pieces from all of them simultaneously:

aria2c "https://host1/file.zip" "https://mirror2/file.zip" "ftp://host3/file.zip"

Important

When you list multiple URLs as command-line arguments like this, they must all point to the same file. If they don't, the download will fail or corrupt. To download different files sequentially, use -Z (see 5.7).

5.4 Resuming an interrupted download

If the previous attempt was made by aria2, just re-run the same command:

aria2c "https://host/file.zip"

If the partial file was downloaded by a web browser or another sequential tool (so there's no .aria2 control file), use -c:

aria2c -c "https://host/partiallydownloadedfile.zip"

Note

-c, --continue currently applies to HTTP(S)/FTP downloads, and resuming a browser-started file only works if that initial download was not multi-segmented.

5.5 Limit download / upload speed

# Cap a single download at 500 KiB/s
aria2c --max-download-limit=500K "https://host/file.zip"

# Cap the combined speed of ALL downloads
aria2c --max-overall-download-limit=2M -i urls.txt

K = 1024, M = 1024K, case-insensitive.

5.6 Download a list of URLs from a file

Put one download per line in a text file:

https://server/file.iso  https://mirror/file.iso
  dir=/iso_images
  out=file.img
https://foo/bar

Then:

aria2c -i urls.txt -j 5

• Multiple URLs for the same file go on one line separated by a TAB.
• Per-download options go on indented lines below the URL (note: no -- prefix in the input file).
• Lines starting with # are comments.

Tip

The input file can be gzip-compressed, and -i - reads the list from standard input, which is handy in pipelines.

5.7 Download several different URLs

To download unrelated files (not mirrors of one file), use -Z so aria2 treats each URL as its own download:

aria2c -Z "https://host/file1" "https://host/file2" "https://host/file3"

5.8 Download through a proxy

aria2c --http-proxy="http://proxy:8080" "https://host/file"

With proxy authentication:

aria2c --http-proxy="http://user:password@proxy:8080" "https://host/file"

Exclude hosts from the proxy:

aria2c --http-proxy="http://proxy:8080" --no-proxy="localhost,127.0.0.1,192.168.0.0/16" "https://host/file"

Tip

aria2 also honors the standard http_proxy, https_proxy, ftp_proxy, all_proxy, and no_proxy environment variables, so it slots into existing proxy setups without extra flags.

5.9 Verify a file's checksum

aria2c --checksum=sha-256=<HEX_DIGEST> "https://example.org/file"

Supported hash types are listed under Hash Algorithms in aria2c -v. To re-validate an already-downloaded file and re-fetch only damaged parts, see -V in section 8.

5.10 Generate URLs with patterns

-P, --parameterized-uri expands brace sets and numeric ranges into multiple URLs:

# Pull the same file from three hosts
aria2c -P "https://{host1,host2,host3}/file.iso"

# Numbered sequence (different files, so -Z is required)
aria2c -Z -P "https://host/image[000-100].png"

# Sequence with a step counter
aria2c -Z -P "https://host/image[A-Z:2].png"

6. BitTorrent Downloads

aria2 is a fully featured BitTorrent client. It supports DHT, peer exchange (PEX), encryption, magnet links, Web-Seeding, UDP trackers, and Local Peer Discovery.

6.1 Download from a torrent file

aria2c "file.torrent"

Download a remote .torrent (and start the torrent immediately, without writing the .torrent to disk):

aria2c --follow-torrent=mem "https://host/file.torrent"

6.2 Download from a magnet link

aria2c "magnet:?xt=urn:btih:248D0A1CD08284299DE78D5C1ED359BB46717D8C&dn=aria2"

Important

Always quote magnet URIs — they almost always contain &. Enable DHT (it's on by default) so aria2 can find peers even when the magnet has no tracker.

6.3 Choose which files to download

Multi-file torrents let you grab only the files you want. First list the contents to find file indexes:

aria2c -S "file.torrent"

idx|path/length
===+======================
  1|dist/base-2.6.18.iso
   |99.9MiB
---+----------------------
  2|dist/driver-2.6.18.iso
   |169.0MiB
---+----------------------

Then select by index (, for a list, - for a range):

aria2c --select-file=1-4,8 "file.torrent"

Note

Because a single torrent piece can span multiple files, files adjacent to the ones you selected may also be partially written. This is by design, not a bug.

6.4 Control seeding

By default aria2 keeps seeding after a torrent completes until the share ratio reaches 1.0. Tune that:

# Stop after ratio 1.0 OR 120 minutes, whichever comes first
aria2c --seed-ratio=1.0 --seed-time=120 "file.torrent"

# Don't seed at all after download finishes
aria2c --seed-time=0 "file.torrent"

6.5 Throttle upload and set ports

# Limit upload to 100 KiB/s
aria2c --max-upload-limit=100K "file.torrent"

# Set the listening port range for incoming peers
aria2c --listen-port=6881-6889,6999 "file.torrent"

Warning

aria2 does not configure your firewall or router. For good BitTorrent performance you must open the chosen TCP ports (and the UDP ports for DHT, default 6881-6999) and set up port forwarding yourself.

6.6 Enable DHT and encryption

# IPv4 DHT (also enables UDP tracker support)
aria2c --enable-dht --dht-listen-port=6881 "file.torrent"

# Force encrypted peer connections (obfuscation)
aria2c --bt-force-encryption=true "file.torrent"

6.7 Download via torrent and HTTP/FTP at the same time

aria2 can pull the same data from a torrent swarm and a regular web/FTP server simultaneously, uploading the web data back into the swarm:

aria2c -T file.torrent "https://host1/file" "ftp://host2/file"

7. Metalink Downloads

A Metalink file bundles multiple mirrors, checksums, and metadata for a download, letting aria2 pick the best sources and verify integrity automatically. Both Metalink 4 (RFC 5854) and Metalink 3.0 are supported.

# Local metalink file
aria2c "file.metalink"

# Remote metalink, kept in memory
aria2c --follow-metalink=mem "https://host/file.metalink"

# Select files by index (use -S to list them first)
aria2c --select-file=1-4,8 "file.metalink"

Express a preference for which mirror/version/language to use:

aria2c --metalink-location=jp,us --metalink-version=1.1 --metalink-language=en-US "file.metalink"

Tip

If a Metalink provides chunk checksums, aria2 validates each chunk as it downloads and re-fetches any that fail — so a Metalink download is self-healing.

8. Checking and Repairing Downloads

The -V, --check-integrity option validates a download against piece hashes (for BitTorrent and checksum-bearing Metalink downloads) and re-downloads only the damaged pieces:

aria2c -V "file.metalink"

aria2c -V "file.torrent"

Tip

This is the efficient way to repair a corrupted download: aria2 hashes what's on disk, then fetches only the bad pieces instead of starting over.

Drop a connection that has stalled below a speed floor:

aria2c --lowest-speed-limit=10K "file.metalink"

9. Using a Configuration File

Rather than retyping options, put them in a config file. By default aria2 reads $HOME/.aria2/aria2.conf (or $XDG_CONFIG_HOME/aria2/aria2.conf). It's one name=value per line, using the long option name without the -- prefix:

# ~/.aria2/aria2.conf
dir=/downloads
max-concurrent-downloads=5
max-connection-per-server=8
split=8
min-split-size=10M
continue=true
listen-port=6881-6999
dht-listen-port=6881
seed-ratio=1.0

Point at a different file, or ignore the config entirely:

aria2c --conf-path=/etc/aria2/aria2.conf "https://host/file"
aria2c --no-conf "https://host/file"            # don't load any config file

Caution

Config files can contain proxy credentials and HTTP/FTP passwords. Restrict the file's permissions: chmod 600 ~/.aria2/aria2.conf.

Note

Use ${HOME} inside the config file to refer to your home directory in path-type options such as dir, input-file, log, out, and the certificate/cookie/session paths — aria2 expands it for those options.

10. Authentication, Cookies, and Headers

HTTP / FTP credentials

aria2c --http-user=alice --http-passwd=secret "https://host/file"
aria2c --ftp-user=bob   --ftp-passwd=secret "ftp://host/file"

Reuse your browser's cookies

aria2c --load-cookies=cookies.txt "https://host/protected/file.zip"

aria2 reads the Firefox 3 / Chromium SQLite cookie store and the classic Mozilla/Netscape cookies.txt format directly.

Note

SQLite cookie formats (Firefox 3, Chromium/Chrome) require an aria2 built with libsqlite3. If Firefox3 Cookie doesn't appear in aria2c -v, only the text cookies.txt format will work.

Custom request headers and referrer

aria2c --header="X-Token: abc123" --header="Accept-Language: en" "https://host/file"
aria2c --referer="https://host/page" "https://host/file"

.netrc

aria2 honors ~/.netrc for HTTP(S)/FTP/SFTP by default. Give it permissions 600 or it will be ignored. Disable netrc with -n, --no-netrc.

11. Running Hooks on Download Events

aria2 can run a command of yours when a download starts, completes, errors, pauses, or stops:

aria2c --on-download-complete=/path/to/hook.sh "https://host/file.iso"

aria2 passes three arguments to your command: the GID, the number of files, and the file path.

$ cat hook.sh
#!/bin/sh
echo "Called with [$1] [$2] [$3]"

$ aria2c --on-download-complete hook.sh "https://example.org/file.iso"
Called with [1] [1] [/path/to/file.iso]

Available event options: --on-download-start, --on-download-pause, --on-download-complete, --on-download-error, --on-download-stop, and --on-bt-download-complete.

12. Running aria2 in the Background

Run aria2 as a daemon (it detaches, changes directory to /, and redirects standard streams to /dev/null):

aria2c -D --enable-rpc --rpc-listen-port=6800

Most people run aria2 as a long-lived background service controlled through its RPC interface (the basis of web UIs like AriaNg and many download managers). Enabling and securing RPC, plus the full method list, is covered in the Admin Guide.

Important

If you enable RPC, always set an authorization token with --rpc-secret=<TOKEN>. Without it, anyone who can reach the RPC port can add, remove, and inspect your downloads.

13. Useful Options at a Glance

The options you'll reach for most often. The Admin Guide has the complete reference for all option groups.

Tip

aria2c --help=#all prints every option. aria2c --help=#http, --help=#bittorrent, --help=#metalink, --help=#rpc, etc. show just one category. aria2c --help=<word> searches option names for that word.

14. Troubleshooting

aria2 reports a numeric exit status describing the last error it hit. Check it after a run with echo $? (Unix) — it's the fastest way to know why a download failed.

Error: exit code 1 — unknown error

Cause: A general failure that doesn't map to a more specific code (often a transient network problem; community issue #1112 is a classic example). Solution: Re-run the command; aria2 resumes automatically. If it persists, add --log=aria2.log --log-level=debug and inspect the log. Prevention: Raise -m, --max-tries and set --retry-wait so transient blips are retried automatically.

Error: exit code 2 — timeout

Cause: The server didn't respond within the timeout window. Solution: Increase -t, --timeout and --connect-timeout. Prevention: For flaky servers, combine a longer timeout with --max-tries and --retry-wait.

Error: exit code 3 — resource not found

Cause: The URL returned 404 / the file doesn't exist on the server. Solution: Verify the URL in a browser. The link may have expired or moved. Prevention: For mirror lists, expect some dead mirrors; aria2 will fall back to live ones.

Error: exit code 6 — network problem

Cause: A connection-level failure occurred. Solution: Check connectivity, DNS, and proxy settings. Re-run to resume.

Error: exit code 8 — server doesn't support resume

Cause: Resume was required but the remote server can't serve a byte range. Also seen as repeated errorCode=8 Invalid range header (community issue #1344). Solution: Restart from scratch with --allow-overwrite=true --remove-control-file=true. Prevention: Some proxies strip range support; try a direct connection or --always-resume=false.

Error: exit code 9 — not enough disk space

Cause: The target volume ran out of room (file space is pre-allocated by default). Solution: Free space or change -d to a larger volume. Adjust --file-allocation (see below).

Error: name resolution failed (exit code 19)

Cause: aria2 couldn't resolve the host name — DNS failure (community issue #774). Solution: Test DNS with another tool. Supply DNS servers explicitly: --async-dns-server=8.8.8.8,1.1.1.1. If your system has no /etc/resolv.conf, this is required. Prevention: On networks with broken IPv6 DNS, add --disable-ipv6=true to skip slow AAAA lookups.

Error: SSL/TLS certificate verification fails

Cause: aria2 verifies HTTPS certificates by default and can't find or validate the CA chain (community issues #757, #2152, and CVE-2026-8367 in #2355). Solution: Point aria2 at your CA bundle: --ca-certificate=/etc/ssl/certs/ca-certificates.crt. As a last resort only, --check-certificate=false disables verification. Prevention: Keep your system CA store current. On macOS/Windows, native TLS (AppleTLS/WinTLS) uses the OS trust store automatically.

Caution

Disabling certificate validation (--check-certificate=false) exposes you to man-in-the-middle attacks. Use it only for trusted hosts on trusted networks, never as a permanent setting.

Error: exit code 13 — file already exists

Cause: The output file already exists and no control file is present. Solution: Use --allow-overwrite=true to restart, or --auto-file-renaming=true (the default for HTTP/FTP) to save under a numbered name.

Error: exit code 32 — checksum validation failed

Cause: The downloaded data didn't match the expected hash. Solution: Re-download. With BitTorrent/Metalink chunk checksums, run -V to repair only the bad pieces.

Slow or zero-speed torrents

Cause: No peers/seeders reachable — often a closed firewall port or disabled DHT (community issues #2351, #2350). Solution: Confirm --enable-dht=true, open and forward the TCP and UDP ports (--listen-port, --dht-listen-port), and add trackers with --bt-tracker=<URI>.

"File allocation takes forever"

Cause: aria2 pre-allocates file space (--file-allocation=prealloc) before downloading. Solution: On modern filesystems (ext4, btrfs, xfs, NTFS) use --file-allocation=falloc for near-instant allocation; or --file-allocation=none to skip it.

Warning

Don't use falloc on legacy filesystems (ext3, FAT32) — it falls back to the slow path and blocks aria2 until allocation finishes.

See exactly what aria2 is doing

aria2c --log=aria2.log --log-level=debug --console-log-level=info "https://host/file"

15. Frequently Asked Questions

Q: Does aria2 have a graphical interface? No. aria2 is a command-line tool. It exposes a JSON-RPC/XML-RPC interface, and many third-party web front-ends (such as AriaNg) and desktop download managers build a GUI on top of it. See the Admin Guide for enabling RPC.

Q: How do I make a single download as fast as possible? Raise both connections-per-server and splits: aria2c -x 16 -s 16 -k 1M "URL". The server must allow that many parallel connections, and the file must be large enough to split (controlled by -k).

Q: Why didn't increasing --split speed anything up? --split is limited by --max-connection-per-server (default 1). Raise -x too.

Q: Can I download from a torrent and a regular web server at the same time? Yes: aria2c -T file.torrent "https://host/file" "ftp://host2/file". aria2 combines both sources and uploads the web data into the swarm.

Q: How do I resume after closing aria2 or rebooting? Re-run the same command in the same directory. aria2 uses the .aria2 control file to continue. For browser-started partial files, add -c.

Q: Where does aria2 store its configuration? $HOME/.aria2/aria2.conf by default, otherwise $XDG_CONFIG_HOME/aria2/aria2.conf. Override with --conf-path, or skip it with --no-conf.

Q: How do I download a list of URLs? Put them in a text file (one entry per line; TAB-separated mirrors on a line) and run aria2c -i urls.txt. The list can also come from stdin with -i -.

Q: How do I stop seeding immediately after a torrent finishes? --seed-time=0. To seed to a target ratio instead, use --seed-ratio.

Q: How do I download only some files from a multi-file torrent? List the files with -S to get their indexes, then --select-file=1-4,8.

Q: My HTTPS download fails with a certificate error. What now? Supply your CA bundle with --ca-certificate=/path/to/ca-certificates.crt. Only disable verification (--check-certificate=false) for hosts you fully trust.

Q: How do I limit aria2's bandwidth so it doesn't saturate my connection? --max-overall-download-limit=2M caps all downloads combined; --max-download-limit=500K caps each one.

Q: Does aria2 support SOCKS proxies? aria2's proxy options target HTTP proxies. SOCKS support is a long-standing community request (issues #153, #1830); route SOCKS via a local HTTP-proxy bridge if you need it.

Q: What protocols and features does my build actually have? Run aria2c -v and read the Enabled Features line. Missing features mean the binary was compiled without the supporting library.

Q: Can aria2 verify a file I download over plain HTTP? Yes — pass the expected hash with --checksum=sha-256=<digest>.

Q: How do I run a command automatically when a download finishes? --on-download-complete=/path/to/script. aria2 passes the GID, file count, and file path as arguments.

Q: aria2 created a ./dev/null file — why? On some platforms, redirection in daemon/quiet modes can create a literal dev/null if /dev/null isn't available as expected (community issue #1535). Run from a normal working directory and ensure /dev/null exists.

16. Getting Help

• Built-in help: aria2c --help=#all (all options), or --help=<keyword> to search.
• Manual: the full aria2 online manual at https://aria2.github.io/manual/en/html/.
• Project home: https://aria2.github.io/
• Source & issues: https://github.com/aria2/aria2

For deployment as a service, the complete option reference, the full RPC API, build-from-source instructions, and architecture details, see the aria2 Admin Guide.