ARIA2C(1)

📦

version 1.37.0 · 8 versions

1.37.0 · alpine 3.24, arch rolling, epel 10, fedora 43, fedora 44, opensuse-leap 16.0 (latest)
1.37.0 · nixos 26.05
1.37.0 · nixpkgs unstable
1.37.0 · ubuntu questing
1.36.0 · debian bookworm, epel 9, ubuntu jammy
1.37.0 · ubuntu noble
1.37.0 · ubuntu resolute, ubuntu stonking
1.37.0 · debian trixie

, in alpine 3.24, arch rolling, epel 10, fedora 43, fedora 44, opensuse-leap 16.0

ARIA2C(1) — `aria2c`, the ultra fast download utility 💖✨

🌸 NAME

aria2c - The ultra fast download utility. That's the whole vibe, bestie. 👑

✨ SYNOPSIS

aria2c [<OPTIONS>] [<URI>|<MAGNET>|<TORRENT_FILE>|<METALINK_FILE>] ...

💫 DESCRIPTION

okay so aria2 is literally a utility for downloading files. The supported protocols are HTTP(S), FTP, SFTP, BitTorrent, and Metalink. aria2 can download a file from multiple sources/protocols and tries to utilize your maximum download bandwidth. It supports downloading a file from HTTP(S)/FTP/SFTP and BitTorrent at the same time, while the data downloaded from HTTP(S)/FTP/SFTP is uploaded to the BitTorrent swarm. Using Metalink chunk checksums, aria2 automatically validates chunks of data while downloading a file. No cap. 🦋

🎀 OPTIONS

NOTE: Most FTP related options are applicable to SFTP as well. Some options are not effective against SFTP (e.g., --ftp-pasv). Not me finding that out the hard way, but okay. 💀

💅 Basic Options

-d, --dir=<DIR> — The directory to store the downloaded file. Basically where your treasure goes. 🏴☠️
-i, --input-file=<FILE> — Downloads the URIs listed in FILE. You can specify multiple sources for a single entity by putting multiple URIs on a single line separated by the TAB character. Additionally, options can be specified after each URI line. Option lines must start with one or more white space characters (SPACE or TAB) and must only contain one option per line. Input files can use gzip compression. When FILE is specified as -, aria2 will read the input from stdin. See the Input File subsection for details. See also the --deferred-input option. See also the --save-session option. Obsessed with the flexibility. 💖
-l, --log=<LOG> — The file name of the log file. If - is specified, log is written to stdout. If empty string("") is specified, or this option is omitted, no log is written to disk at all. So if you're a no-log girlie, that's valid. 🎀
-j, --max-concurrent-downloads=<N> — Set the maximum number of parallel downloads for every queue item. See also the --split option. Default: 5

NOTE: --max-concurrent-downloads limits the number of items which are downloaded concurrently. --split and --min-split-size affect the number of connections inside each item. Imagine that you have an input file (see --input-file option) like this:

http://example.com/foo
http://example.com/bar

Here is 2 download items. aria2 can download these items concurrently if the value more than or equal 2 is given to --max-concurrent-downloads. In each download item, you can configure the number of connections using --split and/or --min-split-size, etc.

-V, --check-integrity [true|false] — Check file integrity by validating piece hashes or a hash of entire file. This option has effect only in BitTorrent, Metalink downloads with checksums or HTTP(S)/FTP downloads with --checksum option. If piece hashes are provided, this option can detect damaged portions of a file and re-download them. If a hash of entire file is provided, hash check is only done when file has been already download. This is determined by file length. If hash check fails, file is re-downloaded from scratch. If both piece hashes and a hash of entire file are provided, only piece hashes are used. Default: false
-c, --continue [true|false] — Continue downloading a partially downloaded file. Use this option to resume a download started by a web browser or another program which downloads files sequentially from the beginning. Currently this option is only applicable to HTTP(S)/FTP downloads. Main character energy for resuming. 🫶
-h, --help[=<TAG>|<KEYWORD>] — The help messages are classified with tags. A tag starts with #. For example, type --help=#http to get the usage for the options tagged with #http. If non-tag word is given, print the usage for the options whose name includes that word. Available Values: #basic, #advanced, #http, #https, #ftp, #metalink, #bittorrent, #cookie, #hook, #file, #rpc, #checksum, #experimental, #deprecated, #help, #all Default: #basic

🌐 HTTP/FTP/SFTP Options

--all-proxy=<PROXY> — Use a proxy server for all protocols. To override a previously defined proxy, use "". You also can override this setting and specify a proxy server for a particular protocol using --http-proxy, --https-proxy and --ftp-proxy options. This affects all downloads. The format of PROXY is [http://][USER:PASSWORD@]HOST[:PORT]. See also ENVIRONMENT section.

NOTE: If user and password are embedded in proxy URI and they are also specified by --{http,https,ftp,all}-proxy-{user,passwd} options, those specified later override prior options. For example, if you specified http-proxy-user=myname, http-proxy-passwd=mypass in aria2.conf and you specified --http-proxy="http://proxy" on the command-line, then you'd get HTTP proxy http://proxy with user myname and password mypass. Another example: if you specified on the command-line --http-proxy="http://user:pass@proxy" --http-proxy-user="myname" --http-proxy-passwd="mypass", then you'd get HTTP proxy http://proxy with user myname and password mypass. One more example: if you specified in command-line --http-proxy-user="myname" --http-proxy-passwd="mypass" --http-proxy="http://user:pass@proxy", then you'd get HTTP proxy http://proxy with user user and password pass.

--all-proxy-passwd=<PASSWD> — Set password for --all-proxy option.
--all-proxy-user=<USER> — Set user for --all-proxy option.
--checksum=<TYPE>=<DIGEST> — Set checksum. TYPE is hash type. The supported hash type is listed in Hash Algorithms in aria2c -v. DIGEST is hex digest. For example, setting sha-1 digest looks like this: sha-1=0192ba11326fe2298c8cb4de616f4d4140213838 This option applies only to HTTP(S)/FTP downloads.
--connect-timeout=<SEC> — Set the connect timeout in seconds to establish connection to HTTP/FTP/proxy server. After the connection is established, this option makes no effect and --timeout option is used instead. Default: 60
--dry-run [true|false] — If true is given, aria2 just checks whether the remote file is available and doesn't download data. This option has effect on HTTP/FTP download. BitTorrent downloads are canceled if true is specified. Default: false
--lowest-speed-limit=<SPEED> — Close connection if download speed is lower than or equal to this value(bytes per sec). 0 means aria2 does not have a lowest speed limit. You can append K or M (1K = 1024, 1M = 1024K). This option does not affect BitTorrent downloads. Default: 0
-x, --max-connection-per-server=<NUM> — The maximum number of connections to one server for each download. Default: 1
--max-file-not-found=<NUM> — If aria2 receives "file not found" status from the remote HTTP/FTP servers NUM times without getting a single byte, then force the download to fail. Specify 0 to disable this option. This options is effective only when using HTTP/FTP servers. The number of retry attempt is counted toward --max-tries, so it should be configured too.

Default: 0

-m, --max-tries=<N> — Set number of tries. 0 means unlimited. See also --retry-wait. Default: 5
-k, --min-split-size=<SIZE> — aria2 does not split less than 2*SIZE byte range. For example, let's consider downloading 20MiB file. If SIZE is 10M, aria2 can split file into 2 range [0-10MiB) and [10MiB-20MiB) and download it using 2 sources(if --split >= 2, of course). If SIZE is 15M, since 2*15M > 20MiB, aria2 does not split file and download it using 1 source. You can append K or M (1K = 1024, 1M = 1024K). Possible Values: 1M -1024M Default: 20M
--netrc-path=<FILE> — Specify the path to the netrc file. Default: $(HOME)/.netrc

NOTE: Permission of the .netrc file must be 600. Otherwise, the file will be ignored.

-n, --no-netrc [true|false] — Disables netrc support. netrc support is enabled by default.

NOTE: netrc file is only read at the startup if --no-netrc is false. So if --no-netrc is true at the startup, no netrc is available throughout the session. You cannot get netrc enabled even if you send --no-netrc=false using aria2.changeGlobalOption().

--no-proxy=<DOMAINS> — Specify a comma separated list of host names, domains and network addresses with or without a subnet mask where no proxy should be used.

NOTE: For network addresses with a subnet mask, both IPv4 and IPv6 addresses work. The current implementation does not resolve the host name in an URI to compare network addresses specified in --no-proxy. So it is only effective if URI has numeric IP addresses.

-o, --out=<FILE> — The file name of the downloaded file. It is always relative to the directory given in --dir option. When the --force-sequential option is used, this option is ignored.

NOTE: You cannot specify a file name for Metalink or BitTorrent downloads. The file name specified here is only used when the URIs fed to aria2 are given on the command line directly, but not when using --input-file, --force-sequential option. Example:

$ aria2c -o myfile.zip "http://mirror1/file.zip" "http://mirror2/file.zip"

--proxy-method=<METHOD> — Set the method to use in proxy request. METHOD is either get or tunnel. HTTPS downloads always use tunnel regardless of this option. Default: get
-R, --remote-time [true|false] — Retrieve timestamp of the remote file from the remote HTTP/FTP server and if it is available, apply it to the local file. Default: false
--reuse-uri [true|false] — Reuse already used URIs if no unused URIs are left. Default: true
--retry-wait=<SEC> — Set the seconds to wait between retries. When SEC > 0, aria2 will retry downloads when the HTTP server returns a 503 response. Default: 0
--server-stat-of=<FILE> — Okay bestie, this is where you tell aria2 to save the server performance receipts. Specify the file name to which the performance profile of the servers is saved. You can load that saved data later using the --server-stat-if option. The file format? It's in the Server Performance Profile subsection below, iykyk. 💾✨
--server-stat-if=<FILE> — Load up the performance profile of the servers from this file. The loaded data gets used in some URI selectors like feedback. Peep the --uri-selector option too. File format is in the Server Performance Profile subsection below. 📂🦋
--server-stat-timeout=<SEC> — Sets a timeout in seconds to invalidate the performance profile of the servers since the last contact to them. Default: 86400 (that's 24 hours, no cap). ⏰💅
-s, --split=<N> — Download a file using N connections. If more than N URIs are given, the first N URIs are used and the remaining URIs are used for backup. If less than N URIs are given, those URIs are used more than once so that N connections total are made simultaneously. The number of connections to the same host is restricted by the --max-connection-per-server option. See also the --min-split-size option. Default: 5. 🚀

NOTE: Some Metalinks regulate the number of servers to connect. aria2 strictly respects them. This means that if Metalink defines the maxconnections attribute lower than N, then aria2 uses the value of this lower value instead of N. 📜👑

--stream-piece-selector=<SELECTOR> — Specify the piece selection algorithm used in HTTP/FTP download. A piece is a fixed length segment which is downloaded in parallel in a segmented download. Default: default. 🧩
- default — Select a piece to reduce the number of connections established. This is reasonable default behavior because establishing a connection is an expensive operation. 💸
- inorder — Select a piece closest to the beginning of the file. This is useful for viewing movies while downloading. --enable-http-pipelining option may be useful to reduce re-connection overhead. Note that aria2 honors --min-split-size option, so it will be necessary to specify a reasonable value to --min-split-size option. 🎬
- random — Select a piece randomly. Like inorder, --min-split-size option is honored. 🎲
- geom — When starting to download a file, select a piece closest to the beginning of the file like inorder, but then exponentially increases space between pieces. This reduces the number of connections established, while at the same time downloads the beginning part of the file first. This is useful for viewing movies while downloading. 📐
-t, --timeout=<SEC> — Set timeout in seconds. Default: 60. ⏳
--uri-selector=<SELECTOR> — Specify URI selection algorithm. The possible values are inorder, feedback, and adaptive. If inorder is given, URI is tried in the order appeared in the URI list. If feedback is given, aria2 uses download speed observed in the previous downloads and chooses the fastest server in the URI list. This also effectively skips dead mirrors. The observed download speed is a part of performance profile of servers mentioned in --server-stat-of and --server-stat-if options. If adaptive is given, selects one of the best mirrors for the first and reserved connections. For supplementary ones, it returns mirrors which has not been tested yet, and if each of them has already been tested, returns mirrors which has to be tested again. Otherwise, it doesn't select anymore mirrors. Like feedback, it uses a performance profile of servers. Default: feedback. 🌐✨

HTTP Specific Options 🌈💖

--ca-certificate=<FILE> — Use the certificate authorities in FILE to verify the peers. The certificate file must be in PEM format and can contain multiple CA certificates. Use --check-certificate option to enable verification. 🔐

NOTE: If you build with OpenSSL or the recent version of GnuTLS which has gnutls_certificate_set_x509_system_trust() function and the library is properly configured to locate the system-wide CA certificates store, aria2 will automatically load those certificates at the startup. 🛠️

NOTE: WinTLS and AppleTLS do not support this option. Instead you will have to import the certificate into the OS trust store. 🚫

--certificate=<FILE> — Use the client certificate in FILE. The certificate must be either in PKCS12 (.p12, .pfx) or in PEM format. PKCS12 files must contain the certificate, a key and optionally a chain of additional certificates. Only PKCS12 files with a blank import password can be opened! When using PEM, you have to specify the private key via --private-key as well. 🪪

NOTE: WinTLS does not support PEM files at the moment. Users have to use PKCS12 files. 💀

NOTE: AppleTLS users should use the KeyChain Access utility to import the client certificate and get the SHA-1 fingerprint from the Information dialog corresponding to that certificate. To start aria2c use --certificate=<SHA-1>. Alternatively PKCS12 files are also supported. PEM files, however, are not supported. 🍎

--check-certificate [true|false] — Verify the peer using certificates specified in --ca-certificate option. Default: true. ✅
--http-accept-gzip [true|false] — Send Accept-Encoding: deflate, gzip request header and inflate response if remote server responds with Content-Encoding: gzip or Content-Encoding: deflate. Default: false. 🗜️

NOTE: Some server responds with Content-Encoding: gzip for files which itself is gzipped file. aria2 inflates them anyway because of the response header. 😭

--http-auth-challenge [true|false] — Send HTTP authorization header only when it is requested by the server. If false is set, then authorization header is always sent to the server. There is an exception: if user name and password are embedded in URI, authorization header is always sent to the server regardless of this option. Default: false. 🔑
--http-no-cache [true|false] — Send Cache-Control: no-cache and Pragma: no-cache header to avoid cached content. If false is given, these headers are not sent and you can add Cache-Control header with a directive you like using --header option. Default: false. 🚫
--http-user=<USER> — Set HTTP user. This affects all URIs. 👤
--http-passwd=<PASSWD> — Set HTTP password. This affects all URIs. 🔒
--http-proxy=<PROXY> — Use a proxy server for HTTP. To override a previously defined proxy, use "". See also the --all-proxy option. This affects all http downloads. The format of PROXY is [http://][USER:PASSWORD@]HOST[:PORT]. 🌐
--http-proxy-passwd=<PASSWD> — Set password for --http-proxy. 🔑
--http-proxy-user=<USER> — Set user for --http-proxy. 👤
--https-proxy=<PROXY> — Use a proxy server for HTTPS. To override a previously defined proxy, use "". See also the --all-proxy option. This affects all https download. The format of PROXY is [http://][USER:PASSWORD@]HOST[:PORT]. 🔒
--https-proxy-passwd=<PASSWD> — Set password for --https-proxy. 🔑
--https-proxy-user=<USER> — Set user for --https-proxy. 👤
--private-key=<FILE> — Use the private key in FILE. The private key must be decrypted and in PEM format. An encrypted key may cause undefined behavior. See also --certificate option. 🔐
--referer=<REFERER> — Set an http referrer (Referer). This affects all http/https downloads. If * is given, the download URI is also used as the referrer. This may be useful when used together with the --parameterized-uri option. 🕵️
--enable-http-keep-alive [true|false] — Enable HTTP/1.1 persistent connection. Default: true. 🔗
--enable-http-pipelining [true|false] — Enable HTTP/1.1 pipelining. Default: false. 🚇

NOTE: There is usually no performance gain from enabling this option. 🐌

--header=<HEADER> — Append HEADER to HTTP request header. You can use this option repeatedly to specify more than one header:

$ aria2c --header="X-A: b78" --header="X-B: 9J1" "http://host/file"

--load-cookies=<FILE> — Load Cookies from FILE using the Firefox3 format (SQLite3), Chromium/Google Chrome (SQLite3) and the Mozilla/Firefox(1.x/2.x)/Netscape format. 🍪

NOTE: If aria2 is built without libsqlite3, then it doesn't support Firefox3 and Chromium/Google Chrome cookie format. 😢

--save-cookies=<FILE> — Save Cookies to FILE in Mozilla/Firefox(1.x/2.x)/Netscape format. If FILE already exists, it is overwritten. Session Cookies are also saved and their expiry values are treated as 0. Possible Values: /path/to/file. 💾
--use-head [true|false] — Use HEAD method for the first request to the HTTP server. Default: false. 📡
--no-want-digest-header [true|false] — Whether to disable Want-Digest header when doing requests. Default: false. 🚫
-U, --user-agent=<USER_AGENT> — Set user agent for HTTP(S) downloads. Default: aria2/$VERSION, $VERSION is replaced by package version. 🕶️

FTP/SFTP Specific Options 📁✨

--ftp-user=<USER> — Set FTP user. This affects all URIs. Default: anonymous. 👤
--ftp-passwd=<PASSWD> — Set FTP password. This affects all URIs. If user name is embedded but password is missing in URI, aria2 tries to resolve password using .netrc. If password is found in .netrc, then use it as password. If not, use the password specified in this option. Default: ARIA2USER@. 🔑
-p, --ftp-pasv [true|false] — Use the passive mode in FTP. If false is given, the active mode will be used. Default: true. 🔄

NOTE: This option is ignored for SFTP transfer. 🚫

--ftp-proxy=<PROXY> — route your FTP downloads through a proxy server, bestie. Wanna nuke a proxy you set earlier? Just throw "" at it. Also peep --all-proxy if you're feeling thorough. This one hits every single FTP download, no exceptions. The shape of PROXY is:

[http://][USER:PASSWORD@]HOST[:PORT]

--ftp-proxy-passwd=<PASSWD> — sets the password for whatever you put in --ftp-proxy. That's it, that's the whole job. 💅
--ftp-proxy-user=<USER> — sets the user for --ftp-proxy. Matching set, slay.
--ftp-type=<TYPE> — picks your FTP transfer type. TYPE is either binary or ascii. Default: binary. 🌸

NOTE: this option gets completely ignored for SFTP transfers. Not "kinda ignored", ignored ignored. 🙈

--ftp-reuse-connection [true|false] — reuse the connection in FTP. Default: true. Recycling is iconic, we love her. ♻️
--ssh-host-key-md=<TYPE>=<DIGEST> — sets a checksum for the SSH host public key, so you can actually validate the server's public key when SFTP is in play. TYPE is the hash type, and the supported hash types are sha-1 or md5. DIGEST is the hex digest. Like, for example:

sha-1=b030503d4de4539dc7885e6f0f5e256704edf4c3

And here's the tea: if you don't set this option (which is the default), then no validation takes place. At all. Just so you know. 👀

🌈 BitTorrent/Metalink Options 🌈

--select-file=<INDEX>... — hand-pick which file you want by its index, no cap. Find that index with the --show-files option. Wanna grab a bunch? Separate them with ,, like 3,6. Wanna grab a whole range? Use -, like 1-5. And yes, , and - can vibe together: 1-5,8,9. When you're rolling with the -M option, the index may shift depending on the query (go read the --metalink-* options for the full lore).

NOTE: in a multi-file torrent, the neighboring files around the one you picked might also get downloaded. That is by design, not a bug — say it with me. A single piece can span several files or just parts of files, and aria2 writes that piece to the appropriate files. It's giving teamwork. 🫶

-S, --show-files [true|false] — prints out the file listing of .torrent, .meta4 and .metalink files, then dips (exits). And for .torrent files specifically, you also get the bonus info — infohash, piece length, all that good stuff. ✨

🔥 BitTorrent Specific Options 🔥

--bt-detach-seed-only [true|false] — kicks seed-only downloads out of the concurrent active download count (that's the -j option, bestie). So picture this: you gave -j3, this option is on, and you've got 3 downloads active — then one of them enters seed mode. Boom, it's excluded from the active count (so now it's 2), and the next download chilling in the queue gets to start. But — and this is important — that seeding item is still recognized as an active download in the RPC method. So don't get it twisted. Default: false
--bt-enable-hook-after-hash-check [true|false] — lets the hook command get invoked after a hash check (see the -V option) in a BitTorrent download. By default, when the hash check succeeds, whatever command you gave --on-bt-download-complete runs. Wanna shut that down? Hand this option a false. Default: true
--bt-enable-lpd [true|false] — turns on Local Peer Discovery, cute. But heads up: if a torrent has the private flag set, aria2 won't use this feature for that download — even if you gave it true. Rules are rules. Default: false
--bt-exclude-tracker=<URI>[,...] — a comma-separated list of BitTorrent tracker announce URIs you want removed. There's a special value * that matches all URIs, so it nukes every announce URI in sight. Oh, and when you're putting * on a shell command-line, do not forget to escape or quote it, or your shell will have opinions. See also the --bt-tracker option.
--bt-external-ip=<IPADDRESS> — sets the external IP address to use for BitTorrent download and DHT. It may get sent to the BitTorrent tracker. For DHT, you should set this so it reports that your local node is downloading a particular torrent — and honestly this is critical if you wanna use DHT in a private network. And even though the name says "external", it'll accept any kind of IP address you throw at it. Flexible queen. 👑
--bt-force-encryption [true|false] — demands BitTorrent message payload encryption with arc4. It's just shorthand for:

--bt-require-crypto --bt-min-crypto-level=arc4

Note: this option does not change the option value of those two — it just acts like them. If you give it true, it denies the legacy BitTorrent handshake and only uses the Obfuscation handshake, and always encrypts the message payload. Default: false

--bt-hash-check-seed [true|false] — if you give it true, then after the hash check (using the --check-integrity option) and the file turns out complete, it keeps seeding that file. If your vibe is "check it and only download when it's damaged or incomplete", then set this bad boy to false. Heads up: this option only does anything on BitTorrent downloads. Default: true
--bt-load-saved-metadata [true|false] — when you're downloading with a magnet link, before it goes off to get torrent metadata from DHT, it first tries to read a file saved by the --bt-save-metadata option. If that works out, it skips the whole DHT metadata download. Efficiency, we love to see it. Default: false
--bt-lpd-interface=<INTERFACE> — uses the given interface for Local Peer Discovery. If you don't specify this option, the default interface gets chosen for you. You can specify an interface name or an IP address. Possible Values: interface, IP address
--bt-max-open-files=<NUM> — the maximum number of files to open in multi-file BitTorrent/Metalink download, globally. Default: 100
--bt-max-peers=<NUM> — the maximum number of peers per torrent. 0 means unlimited, go wild. See also the --bt-request-peer-speed-limit option. Default: 55
--bt-metadata-only [true|false] — downloads the metadata only. The file(s) described in that metadata will not be downloaded. This option only has an effect when a BitTorrent Magnet URI is used. See also the --bt-save-metadata option. Default: false
--bt-min-crypto-level=plain|arc4 — sets the minimum level of encryption method. If a peer offers several encryption methods, aria2 picks the lowest one that still satisfies the level you gave. Default: plain
--bt-prioritize-piece=head[=<SIZE>],tail[=<SIZE>] — tries to download the first and last pieces of each file first. Super useful for previewing files, ngl. The argument can contain 2 keywords: head and tail. To include both, separate them with a comma. Each keyword can take one parameter, SIZE. So if you say head=<SIZE>, the pieces in the range of the first SIZE bytes of each file get higher priority. tail=<SIZE> means the range of the last SIZE bytes of each file. SIZE can include K or M (1K = 1024, 1M = 1024K). If SIZE is omitted, SIZE=1M is used.
--bt-remove-unselected-file [true|false] — removes the unselected files when the download completes in BitTorrent. To select files, use the --select-file option. If you don't use it, all files are assumed to be selected.

Please use this option with care, bestie, because it will literally remove files from your disk. Like, actually delete them. For real. 💀

Default: false

--bt-require-crypto [true|false] — if you give it true, aria2 refuses to accept and establish a connection with the legacy BitTorrent handshake (\19BitTorrent protocol). So aria2 always uses the Obfuscation handshake. No negotiating. Default: false
--bt-request-peer-speed-limit=<SPEED> — if the whole download speed of every torrent is lower than SPEED, aria2 temporarily bumps up the number of peers to chase more download speed. Configuring this with your preferred download speed can boost your speeds in some cases, fr fr. You can append K or M (1K = 1024, 1M = 1024K). Default: 50K
--bt-save-metadata [true|false] — saves the metadata as a .torrent file. Only has an effect when a BitTorrent Magnet URI is used. The file name is the hex encoded info hash with the suffix .torrent, and it saves to the same directory where the download file is saved. If the same file already exists, the metadata is not saved — no overwriting, no drama. See also the --bt-metadata-only option. Default: false
--bt-seed-unverified [true|false] — seeds previously downloaded files without verifying piece hashes. Living dangerously, respect. Default: false
--bt-stop-timeout=<SEC> — stops the BitTorrent download if the download speed is 0 for SEC consecutive seconds. If you give it 0, this whole feature is disabled. Default: 0
--bt-tracker=<URI>[,...] — a comma-separated list of additional BitTorrent tracker announce URIs. These URIs are not affected by the --bt-exclude-tracker option, because they get added after the URIs in --bt-exclude-tracker are removed. Order of operations, iykyk.
--bt-tracker-connect-timeout=<SEC> — sets the connect timeout in seconds for establishing a connection to the tracker. Once the connection is established, this option does nothing anymore, and the --bt-tracker-timeout option takes over instead. Default: 60
--bt-tracker-interval=<SEC> — sets the interval in seconds between tracker requests. This completely overrides the interval value — aria2 just uses this value and ignores both the min interval and the interval value in the tracker's response. If you set it to 0, aria2 figures out the interval based on the tracker's response and the download progress. Default: 0
--bt-tracker-timeout=<SEC> — sets the timeout in seconds. Default: 60
--dht-entry-point=<HOST>:<PORT> — sets the host and port as an entry point to the IPv4 DHT network. 🚪
--dht-entry-point6=<HOST>:<PORT> — same energy, but for the IPv6 DHT network. 💜
--dht-file-path=<PATH> — changes the IPv4 DHT routing table file to PATH. Default: $HOME/.aria2/dht.dat if present, otherwise $XDG_CACHE_HOME/aria2/dht.dat.
--dht-file-path6=<PATH> — changes the IPv6 DHT routing table file to PATH. Default: $HOME/.aria2/dht6.dat if present, otherwise $XDG_CACHE_HOME/aria2/dht6.dat.
--dht-listen-addr6=<ADDR> — specifies the address to bind the socket for IPv6 DHT. It should be a global unicast IPv6 address of the host, so no funny business with local ones.
--dht-listen-port=<PORT>... — sets the UDP listening port used by DHT (IPv4, IPv6) and the UDP tracker. You can specify multiple ports using ,, for example 6881,6885. You can also use - for a range: 6881-6999. And yes, , and - can be used together. Default: 6881-6999

NOTE: make sure those specified ports are open for incoming UDP traffic. Do the port-forwarding homework, bestie. 🧚

--dht-message-timeout=<SEC> — sets the timeout in seconds. Default: 10
--enable-dht [true|false] — turns on IPv4 DHT 💫 and guess what, it also switches on UDP tracker support while it's at it. BUT if a torrent has the private flag set, aria2 straight up will not use DHT for that download, even if you said true. Default: true
--enable-dht6 [true|false] — turns on IPv6 DHT ✨ same deal with the private flag: private torrent = no DHT for it, even with true. Wanna pick the port it listens on? That's --dht-listen-port's job. Also go peek at --dht-listen-addr6 👀
--enable-peer-exchange [true|false] — enables the Peer Exchange extension 🫶 and yeah, private flag in a torrent disables this for that download too, even if you passed true. Default: true
--follow-torrent=true|false|mem — okay so: if you say true or mem, then whenever a file with suffix .torrent or content type application/x-bittorrent gets downloaded, aria2 parses it as a torrent file and downloads the files inside it 🔥. Say mem and the torrent file never touches your disk, it just vibes in memory 🧠. Say false and the .torrent file gets downloaded to disk but is not parsed as a torrent and its contents are not downloaded. Default: true
-O, --index-out=<INDEX>=<PATH> — sets the file path for the file with index=INDEX 🎀. Wanna know the index? Use --show-files, bestie. PATH is a relative path to whatever --dir says. You can stack this option multiple times. And yes, this is how you name your BitTorrent output files 💅
--listen-port=<PORT>... — sets the TCP port number for BitTorrent downloads. Multiple ports? Separate them with , like 6881,6885 💖. You can also use - for a range: 6881-6999. And you can mix , and - together: 6881-6889,6999. Default: 6881-6999

NOTE: make sure those ports are actually open for incoming TCP traffic, okay?? 🚪✨

--max-overall-upload-limit=<SPEED> — caps your overall upload speed in bytes/sec. 0 means unrestricted, go wild 🌈. You can tack on K or M (1K = 1024, 1M = 1024K). Per-torrent limit? That's --max-upload-limit. Default: 0
-u, --max-upload-limit=<SPEED> — caps upload speed per each torrent, in bytes/sec. 0 means unrestricted 🦋. Same K / M deal (1K = 1024, 1M = 1024K). For the overall cap use --max-overall-upload-limit. Default: 0
--peer-id-prefix=<PEER_ID_PREFIX> — sets the prefix of the peer ID 👑. A BitTorrent peer ID is exactly 20 bytes long. Give more than 20 bytes and only the first 20 get used. Give less than 20 and random byte data gets padded on until it hits 20 bytes.

Default: A2-$MAJOR-$MINOR-$PATCH-, where $MAJOR, $MINOR and $PATCH get swapped for the major, minor and patch version numbers respectively. So like, aria2 version 1.18.8 has prefix ID A2-1-18-8- 💫

--peer-agent=<PEER_AGENT> — sets the string used during the BitTorrent extended handshake for the peer's client version 🌸.

Default: aria2/$MAJOR.$MINOR.$PATCH, where $MAJOR, $MINOR and $PATCH are replaced by major, minor and patch version number respectively. For instance, aria2 version 1.18.8 has peer agent aria2/1.18.8.

--seed-ratio=<RATIO> — sets the share ratio 🍓. Completed torrents keep seeding until the share ratio hits RATIO. Strongly encouraged to put 1.0 or more here, bestie. Put 0.0 if you plan to seed forever regardless of ratio, main character behaviour honestly 👑. If you also pass --seed-time, seeding stops as soon as at least one of the two conditions is satisfied. Default: 1.0
--seed-time=<MINUTES> — sets seeding time in (fractional) minutes ⏳. Also go look at --seed-ratio.

NOTE: --seed-time=0 disables seeding after the download completes. Zero. None. Bye 💀

-T, --torrent-file=<TORRENT_FILE> — the path to the .torrent file 🎀. Honestly you don't even need this option, because you can just pass .torrent files directly without --torrent-file. Iconic.

🌟 Metalink Specific Options 🌟

--follow-metalink=true|false|mem — if true or mem, then when a file with suffix .meta4 or .metalink, or content type application/metalink4+xml or application/metalink+xml, gets downloaded, aria2 parses it as a metalink file and downloads the files mentioned in it ✨. With mem, the metalink file isn't written to disk, it's just kept in memory 🧠. With false, the .metalink file is downloaded to disk but is not parsed as a metalink file and its contents are not downloaded. Default: true
--metalink-base-uri=<URI> — sets the base URI used to resolve relative URIs in the metalink:url and metalink:metaurl elements in a metalink file stored on your local disk 🦋. If URI points to a directory, it must end with /. Periodt.
-M, --metalink-file=<METALINK_FILE> — the file path to a .meta4 and .metalink file 💖. Reads input from stdin when - is specified. You don't need this option either, since you can specify .metalink files without --metalink-file. Slay.
--metalink-language=<LANGUAGE> — the language of the file to download 🌸
--metalink-location=<LOCATION>[,...] — the location of the preferred server. A comma-delimited list of locations is acceptable, for example jp,us 🗺️
--metalink-os=<OS> — the operating system of the file to download 💻
--metalink-version=<VERSION> — the version of the file to download 🎀
--metalink-preferred-protocol=<PROTO> — sets the preferred protocol. Possible values are http, https, ftp and none. Say none to disable this feature entirely. Default: none
--metalink-enable-unique-protocol [true|false] — if true, and a mirror in a metalink file has several protocols available, aria2 uses one of them 🙈. Use --metalink-preferred-protocol to say which one you prefer. Default: true

💅 RPC Options 💅

--enable-rpc [true|false] — enables the JSON-RPC/XML-RPC server 🔥. Strongly recommended to set a secret authorization token with --rpc-secret. Also see --rpc-listen-port. Default: false
--pause [true|false] — pauses the download after it's added. Only does anything when --enable-rpc=true is given ✋. Default: false
--pause-metadata [true|false] — pauses downloads created as a result of metadata download 🧠. There are 3 types of metadata downloads in aria2: (1) downloading a .torrent file. (2) downloading torrent metadata using a magnet link. (3) downloading a metalink file. These metadata downloads generate downloads using their metadata, and this option pauses those follow-up downloads. Only effective when --enable-rpc=true is given. Default: false
--rpc-allow-origin-all [true|false] — adds the Access-Control-Allow-Origin header field with value * to the RPC response 🌈. Default: false
--rpc-certificate=<FILE> — uses the certificate in FILE for the RPC server 🔐. The certificate has to be either PKCS12 (.p12, .pfx) or PEM format.

PKCS12 files must contain the certificate, a key, and optionally a chain of additional certificates. Only PKCS12 files with a blank import password can be opened! Like, only those.

When using PEM, you also have to specify the private key via --rpc-private-key. Use --rpc-secure to enable encryption.

NOTE: WinTLS does not support PEM files at the moment. Users have to use PKCS12 files. Sorry bestie 😭

NOTE: AppleTLS users should use the KeyChain Access utility to first generate a self-signed SSL-Server certificate, e.g. using the wizard, and get the SHA-1 fingerprint from the Information dialog corresponding to that new certificate. To start aria2c with --rpc-secure, use --rpc-certificate=<SHA-1>. Alternatively PKCS12 files are also supported. PEM files, however, are not supported. 🍎💀

--rpc-listen-all [true|false] — listens for incoming JSON-RPC/XML-RPC requests on all network interfaces 🌐. If false, it only listens on the local loopback interface. Default: false
--rpc-listen-port=<PORT> — sets a port number for the JSON-RPC/XML-RPC server to listen to. Possible Values: 1024 - 65535. Default: 6800
--rpc-max-request-size=<SIZE> — sets the max size of a JSON-RPC/XML-RPC request. If aria2 sees the request is more than SIZE bytes, it drops the connection 💀. Default: 2M
--rpc-passwd=<PASSWD> — sets the JSON-RPC/XML-RPC password 🔑

WARNING: --rpc-passwd will be deprecated in a future release. Migrate to --rpc-secret as soon as possible, bestie, fr fr 🙏

--rpc-private-key=<FILE> — uses the private key in FILE for the RPC server 🔐. The private key must be decrypted and in PEM format. Use --rpc-secure to enable encryption. See also --rpc-certificate.
--rpc-save-upload-metadata [true|false] — saves the uploaded torrent or metalink metadata in the directory specified by --dir 💾. The file name is the SHA-1 hash hex string of the metadata plus an extension. For torrent, the extension is .torrent. For metalink, it's .meta4. If false is given, the downloads added by aria2.addTorrent() or aria2.addMetalink() will not be saved by --save-session. Default: true
--rpc-secret=<TOKEN> — sets the RPC secret authorization token 🔑. Read "RPC authorization secret token" to know how this option value is used.
--rpc-secure [true|false] — RPC transport gets encrypted by SSL/TLS 🔒. The RPC clients must use the https scheme to reach the server. For WebSocket clients, use the wss scheme. Use --rpc-certificate and --rpc-private-key to specify the server certificate and private key.
--rpc-user=<USER> — sets the JSON-RPC/XML-RPC user 🙈

WARNING: --rpc-user will be deprecated in a future release. Migrate to --rpc-secret as soon as possible 🫶

⭐ Advanced Options ⭐

--allow-overwrite [true|false] — restarts the download from scratch if the corresponding control file doesn't exist 😭. See also --auto-file-renaming. Default: false

--allow-piece-length-change [true|false] — okay so if you pass false, aria2 straight up aborts the download when the piece length doesn't match the one in the control file. Give it true and you can keep going, but bestie, you will lose some download progress. Default: false 💀
--always-resume [true|false] — the "we don't give up" button 🫶 true means aria2 always tries to resume, and if resuming isn't possible, it aborts. false means: when every URI you gave doesn't support resume, or aria2 runs into N URIs that don't support resume (N being whatever you set with --max-resume-failure-tries), it just downloads the file from scratch. Peep --max-resume-failure-tries for that. Default: true
--async-dns [true|false] — turn on asynchronous DNS. Default: true ✨
--async-dns-server=<IPADDRESS>[,...] — a comma-separated list of DNS server addresses for the async DNS resolver to use. Normally the async resolver reads its DNS server addresses from /etc/resolv.conf, but when you use this option it uses your list instead of the ones in that file. Both IPv4 and IPv6 addresses are welcome. This one's a lifesaver when your system has no /etc/resolv.conf and you don't have permission to create one. 💖
--auto-file-renaming [true|false] — renames the file if a file with the same name already exists. Heads up: this only works for HTTP(S)/FTP downloads. The new name gets a dot and a number (1..9999) tacked on after the name, but before the file extension if there is one. Default: true 🌸
--auto-save-interval=<SEC> — saves a control file (*.aria2) every SEC seconds. If you give it 0, no control file gets saved during the download — but aria2 still saves one when it stops, no matter what value you picked. Possible values live between 0 to 600. Default: 60 ⏰
--conditional-get [true|false] — only download the file when your local copy is older than the remote one. This works with HTTP(S) downloads only. It does not work if a file size is specified in Metalink, and it also ignores the Content-Disposition header. If a control file exists, this option gets ignored entirely. It uses the If-Modified-Since header to conditionally grab only newer files. When it checks the modification time of the local file, it uses the file name you supplied (see --out) or the file name part in the URI if --out isn't specified. To overwrite an existing file, you need --allow-overwrite. Default: false 🙈
--conf-path=<PATH> — change the config file path to PATH. Default: $HOME/.aria2/aria2.conf if present, otherwise $XDG_CONFIG_HOME/aria2/aria2.conf. 🎀
--console-log-level=<LEVEL> — sets the log level for console output. LEVEL is either debug, info, notice, warn or error. Default: notice 📝
--content-disposition-default-utf8 [true|false] — treats the quoted string in the Content-Disposition header as UTF-8 instead of ISO-8859-1 — think the filename parameter — but not the extended version filename*. Default: false
-D, --daemon [true|false] — run as a daemon 👑 The current working directory gets changed to /, and standard input, standard output and standard error all get redirected to /dev/null. Default: false
--deferred-input [true|false] — with true, aria2 does not read all the URIs and options from the file you specified with --input-file at startup. Instead it reads them one by one, later, whenever it needs them. This can lower memory usage if your input file is stacked with URIs to download. With false, aria2 reads all URIs and options at startup. Default: false

WARNING: 🚨 --deferred-input gets disabled when --save-session is used together with it. No cap.

--disable-ipv6 [true|false] — disables IPv6. Super useful if you're stuck with broken DNS and want to dodge that painfully slow AAAA record lookup. Default: false 🐌
--disk-cache=<SIZE> — enables the disk cache. If SIZE is 0, the disk cache is off. This feature caches downloaded data in memory, growing to at most SIZE bytes. The cache storage is made per aria2 instance and shared across all downloads. The glow-up here? It reduces disk I/O because data gets written in bigger units and reordered by the file offset. And if hash checking is involved and the data's already cached in memory, we don't have to read it from disk at all. ✨ SIZE can include K or M (1K = 1024, 1M = 1024K). Default: 16M
--download-result=<OPT> — changes how Download Results gets formatted. If OPT is default, it prints GID, status, average download speed and path/URI. When multiple files are involved, only the path/URI of the first requested file is printed and the rest get omitted. If OPT is full, it prints GID, status, average download speed, percentage of progress and path/URI — with the percentage of progress and path/URI printed for each requested file in each row. If OPT is hide, Download Results is hidden. Default: default 💅
--dscp=<DSCP> — sets the DSCP value in outgoing IP packets of BitTorrent traffic, for QoS. It only sets the DSCP bits in the TOS field of IP packets, not the whole field. Careful here: if you're pulling values from /usr/include/netinet/ip.h, divide them by 4 (otherwise your values come out wrong — like, your CS1 class would turn into CS4 😭). If you're taking commonly used values from RFC, network vendors' documentation, Wikipedia or anywhere else, use them as they are.
--rlimit-nofile=<NUM> — sets the soft limit of open file descriptors. This will only actually do anything when:
- a. The system supports it (posix)
- b. The limit does not exceed the hard limit.
- c. The specified limit is larger than the current soft limit.

It's equivalent to setting nofile via ulimit, except it will never decrease the limit. This option is only available on systems supporting the rlimit API. 🧚

--enable-color [true|false] — enables color output for a terminal. Default: true 🌈
--enable-mmap [true|false] — maps files into memory. Heads up: this may not work if the file space isn't pre-allocated — see --file-allocation. Default: false
--event-poll=<POLL> — picks the method for polling events. Possible values are epoll, kqueue, port, poll and select. Each of epoll, kqueue, port and poll is available if your system supports it. epoll is available on recent Linux. kqueue is available on various *BSD systems, Mac OS X included. port is available on Open Solaris. The default value may vary depending on the system you use. 🦋
--file-allocation=<METHOD> — picks the file allocation method. none doesn't pre-allocate file space. prealloc pre-allocates file space before the download begins, which may take some time depending on the file size. If you're on newer file systems like ext4 (with extents support), btrfs, xfs or NTFS (MinGW build only), falloc is your best choice — it allocates large (few GiB) files almost instantly. Do not use falloc with legacy file systems like ext3 and FAT32, because it takes almost the same time as prealloc and it blocks aria2 entirely until allocation finishes. Also, falloc may not be available if your system doesn't have the posix_fallocate(3) function. trunc uses the ftruncate(2) system call or a platform-specific counterpart to truncate a file to a specified length.

Possible Values: none, prealloc, trunc, falloc Default: prealloc

WARNING: ⚠️ Using trunc seemingly allocates disk space super fast, but what it's actually doing is setting the file length metadata in the file system — it does not allocate disk space at all. Which means it does not help you avoid fragmentation. Periodt.

NOTE: 🎀 In multi file torrent downloads, the files adjacent forward to the specified files are also allocated if they share the same piece.

--force-save [true|false] — saves the download with the --save-session option even if the download is completed or removed. This option also saves the control file in those situations. Handy for saving BitTorrent seeding, which gets recognized as a completed state. Default: false 💾
--save-not-found [true|false] — saves the download with the --save-session option even if the file was not found on the server. This option also saves the control file in those situations. Default: true
--gid=<GID> — sets the GID manually. aria2 identifies each download by an ID called the GID. The GID must be a hex string of 16 characters, so [0-9a-fA-F] are allowed and leading zeros must not be stripped. The GID of all 0 is reserved and must not be used. The GID must be unique — otherwise an error is reported and the download isn't added. This option is useful when restoring sessions saved with --save-session. If you don't use this option, aria2 generates a new GID for you. 🔑
--hash-check-only [true|false] — if true, after the hash check using the --check-integrity option, abort the download whether or not the download is complete. Default: false
--human-readable [true|false] — prints sizes and speed in human readable format (like 1.2Ki, 3.4Mi) in the console readout. Default: true 🌸
--interface=<INTERFACE> — binds sockets to a given interface. You can specify an interface name, IP address or host name. Possible Values: interface, IP address, host name

NOTE: 💜 If an interface has multiple addresses, it is highly recommended to specify the IP address explicitly. See also --disable-ipv6. And if your system doesn't have getifaddrs(3), this option doesn't accept an interface name.

--keep-unfinished-download-result [true|false] — keeps unfinished download results even if doing so pushes past --max-download-result. This is useful when all unfinished downloads must be saved in the session file (see the --save-session option). Please keep in mind there is no upper bound to the number of unfinished download results it keeps 😳 — if that's not the vibe you want, turn this option off. Default: true
--max-download-result=<NUM> — sets the max number of download results kept in memory, bestie. Download results = completed / error / removed downloads, all of it. They live in a FIFO queue and it can hold at most NUM of them. When the queue is full and a new download result shows up, the oldest one gets yeeted from the front and the new one gets pushed to the back. 🫠 Heads up: setting a big number here may result in high memory consumption after thousands of downloads, so like… be mindful. Specifying 0 means no download result is kept at all. Note that unfinished downloads are kept in memory regardless of this option value — see --keep-unfinished-download-result for that. Default: 1000
--max-mmap-limit=<SIZE> — sets the maximum file size that can enable mmap (peep the --enable-mmap option 💅). The file size here = the sum of all files contained in one download. So like, if a download contains 5 files, then file size is the total size of those files. If the file size is strictly greater than the size you put in this option, mmap gets disabled. Default: 9223372036854775807
--max-resume-failure-tries=<N> — when used with --always-resume=false, aria2 downloads the file from scratch when it detects N number of URIs that don't support resume. If N is 0, aria2 downloads from scratch when all given URIs don't support resume. See the --always-resume option. Default: 0
--min-tls-version=<VERSION> — specify the minimum SSL/TLS version to enable. Possible Values: TLSv1.1, TLSv1.2, TLSv1.3 Default: TLSv1.2
--multiple-interface=<INTERFACES> — a comma separated list of interfaces to bind sockets to. Requests get split among the interfaces to achieve link aggregation (slay). You can specify interface name, IP address and hostname. If --interface is used, this option will be ignored. Possible Values: interface, IP address, hostname
--log-level=<LEVEL> — set the log level to output. LEVEL is either debug, info, notice, warn or error. Default: debug
--on-bt-download-complete=<COMMAND> — for BitTorrent, a command specified in --on-download-complete is called after download completed and seeding is over. On the other hand, this option sets the command to be executed after download completed but before seeding. See Event Hook for more details about COMMAND. Possible Values: /path/to/command
--on-download-complete=<COMMAND> — set the command to be executed after download completed. See Event Hook for more details about COMMAND. See also --on-download-stop. Possible Values: /path/to/command
--on-download-error=<COMMAND> — set the command to be executed after download aborted due to error. 😭 See Event Hook for more details about COMMAND. See also --on-download-stop. Possible Values: /path/to/command
--on-download-pause=<COMMAND> — set the command to be executed after download was paused. See Event Hook for more details about COMMAND. Possible Values: /path/to/command
--on-download-start=<COMMAND> — set the command to be executed after download got started. See Event Hook for more details about COMMAND. Possible Values: /path/to/command
--on-download-stop=<COMMAND> — set the command to be executed after download stopped. You can override the command for a particular download result using --on-download-complete and --on-download-error. If they are specified, the command specified in this option is not executed. See Event Hook for more details about COMMAND. Possible Values: /path/to/command
--optimize-concurrent-downloads [true|false|<A>:<B>] — optimizes the number of concurrent downloads according to the bandwidth available. aria2 uses the download speed observed in previous downloads to adapt the number of downloads launched in parallel according to the rule N = A + B Log10(speed in Mbps). The coefficients A and B can be customized in the option arguments with A and B separated by a colon. The default values (A=5, B=25) lead to using typically 5 parallel downloads on 1Mbps networks and above 50 on 100Mbps networks. The number of parallel downloads stays constrained under the maximum defined by the --max-concurrent-downloads parameter. Default: false
--piece-length=<LENGTH> — set a piece length for HTTP/FTP downloads. This is the boundary when aria2 splits a file, and all splits occur at multiples of this length. This option will be ignored in BitTorrent downloads. It will also be ignored if the Metalink file contains piece hashes. Default: 1M

NOTE: The possible use case of --piece-length is changing the request range in one HTTP pipelined request. To enable HTTP pipelining use --enable-http-pipelining.

--show-console-readout [true|false] — show console readout. Default: true
--stderr [true|false] — redirect all console output that would otherwise be printed in stdout to stderr. Default: false
--summary-interval=<SEC> — set the interval in seconds to output download progress summary. Setting 0 suppresses the output. Default: 60
-Z, --force-sequential [true|false] — fetch URIs in the command-line sequentially and download each URI in a separate session, like the usual command-line download utilities. Default: false
--max-overall-download-limit=<SPEED> — set max overall download speed in bytes/sec. 0 means unrestricted. You can append K or M (1K = 1024, 1M = 1024K). To limit the download speed per download, use --max-download-limit. Default: 0
--max-download-limit=<SPEED> — set max download speed per each download in bytes/sec. 0 means unrestricted. You can append K or M (1K = 1024, 1M = 1024K). To limit the overall download speed, use --max-overall-download-limit. Default: 0
--no-conf [true|false] — disable loading the aria2.conf file.
--no-file-allocation-limit=<SIZE> — no file allocation is made for files whose size is smaller than SIZE. You can append K or M (1K = 1024, 1M = 1024K). Default: 5M
-P, --parameterized-uri [true|false] — enable parameterized URI support. You can specify a set of parts: http://{sv1,sv2,sv3}/foo.iso. Also you can specify numeric sequences with a step counter: http://host/image[000-100:2].img. A step counter can be omitted. If all URIs do not point to the same file, such as the second example above, the -Z option is required. Default: false
-q, --quiet [true|false] — make aria2 quiet (no console output). Default: false
--realtime-chunk-checksum [true|false] — validate a chunk of data by calculating checksum while downloading a file, if chunk checksums are provided. Default: true
--remove-control-file [true|false] — remove the control file before download. Using with --allow-overwrite=true, download always starts from scratch. This will be useful for users behind a proxy server which disables resume. 🫶
--save-session=<FILE> — save error/unfinished downloads to FILE on exit. You can pass this output file to aria2c with the --input-file option on restart. If you like the output to be gzipped, append a .gz extension to the file name. Please note that downloads added by aria2.addTorrent() and aria2.addMetalink() RPC method and whose metadata could not be saved as a file are not saved. Downloads removed using aria2.remove() and aria2.forceRemove() will not be saved. GID is also saved with gid, but there are some restrictions — see below. 👇

NOTE: Normally, GID of the download itself is saved. But some downloads use metadata (e.g., BitTorrent and Metalink). In this case, there are some restrictions. - magnet URI, and followed by torrent download — GID of BitTorrent metadata download is saved. - URI to torrent file, and followed by torrent download — GID of torrent file download is saved. - URI to metalink file, and followed by file downloads described in metalink file — GID of metalink file download is saved. - local torrent file — GID of torrent download is saved. - local metalink file — any meaningful GID is not saved.

--save-session-interval=<SEC> — save error/unfinished downloads to a file specified by --save-session every SEC seconds. If 0 is given, the file will be saved only when aria2 exits. Default: 0
--socket-recv-buffer-size=<SIZE> — set the maximum socket receive buffer in bytes. Specifying 0 will disable this option. This value will be set to the socket file descriptor using the SO_RCVBUF socket option with a setsockopt() call. Default: 0
--stop=<SEC> — stop application after SEC seconds has passed. If 0 is given, this feature is disabled. Default: 0
--stop-with-process=<PID> — stop application when process PID is not running. This is useful if the aria2 process is forked from a parent process. The parent process can fork aria2 with its own pid, and when the parent process exits for some reason, aria2 can detect it and shut itself down. 💀
--truncate-console-readout [true|false] — truncate console readout to fit in a single line. Default: true
-v, --version — print the version number, copyright and the configuration information and exit. 👑

🎀 Notes for Options 🎀

Optional arguments ✨

The options that have their argument surrounded by square brackets ([]) take an optional argument. Usually, omitting the argument is evaluated to true. If you use the short form of these options (such as -V) and give an argument, then the option name and its argument should be concatenated (e.g. -Vfalse). If any spaces are inserted between the option name and the argument, the argument will be treated as a URI — and usually that is not what you expect. 😭

Units (K and M) 💅

Some options take K and M to conveniently represent 1024 and 1048576 respectively. aria2 detects these characters in a case-insensitive way. In other words, k and m can be used as well as K and M respectively. 🌸

✨ URI, MAGNET, TORRENT_FILE, METALINK_FILE ✨

okay so bestie, you can just. pile URIs onto the command line. multiple. as many as you want. BUT 💀 unless you pass --force-sequential, every single URI has to point at the same file, or the whole download just dies. no cap.

You can also throw in an arbitrary number of BitTorrent Magnet URIs 🧲 — but heads up, they are always treated as a separate download. Both hex encoded 40 characters Info Hash and Base32 encoded 32 characters Info Hash are supported, because we're generous like that. Multiple tr parameters? Supported. And since a BitTorrent Magnet URI is likely to contain a & character, it is highly recommended to always quote the URI with single(') or double(") quotation. Also strongly recommended: turn on DHT, especially when the tr parameter is missing. Want the full lore? It's at http://www.bittorrent.org/beps/bep_0009.html. iykyk 💅

You can also specify an arbitrary number of torrent files and Metalink documents stored on a local drive. same deal — always treated as a separate download. Both Metalink4 and Metalink version 3.0 are supported. iconic.

And here's the fun part 🌈 you can specify both a torrent file with -T and URIs. Do that and you're downloading a file from both the torrent swarm and an HTTP(S)/FTP/SFTP server at the same time, while the data from HTTP(S)/FTP/SFTP gets uploaded to the torrent swarm. teamwork!! For single file torrents, the URI can be a complete URI pointing to the resource, or if the URI ends with /, the name in the torrent file is added. For multi-file torrents, the name and path are added to form a URI for each file. slay.

NOTE: make sure that URI is quoted with single(') or double(") quotation if it contains & or any characters that have special meaning in shell. shell will absolutely humble you otherwise 🫶

💖 Resuming Download 💖

Usually? You just resume by issuing the same command again (aria2c URI) if the previous transfer was made by aria2. easy. no thoughts, head empty, it just works ✨

But if the previous transfer was made by a browser or a wget-like sequential download manager, then use --continue to continue the transfer. that's the one. don't forget it 🎀

🦋 Event Hook 🦋

aria2 lets you specify an arbitrary command to run after a specific event happens. it's giving automation. Currently these options are available:

--on-bt-download-complete
--on-download-pause
--on-download-complete
--on-download-start
--on-download-error
--on-download-stop

When the command is executed, aria2 passes 3 arguments to it: GID, the number of files, and file path. For HTTP, FTP, and SFTP downloads, usually the number of files is 1. A BitTorrent download can contain multiple files though. If the number of files is more than one, the file path is the first one — in other words, this is the value of the path key of the first struct whose selected key is true in the response of the aria2.getFiles() RPC method. If you want to get all the file paths, consider using JSON-RPC/XML-RPC. Also please note that the file path may change during download in HTTP because of redirection or Content-Disposition header. 🙈

Let's see an example of how arguments are passed to the command:

$ cat hook.sh
#!/bin/sh
echo "Called with [$1] [$2] [$3]"
$ aria2c --on-download-complete hook.sh http://example.org/file.iso
Called with [1] [1] [/path/to/file.iso]

look at her go 💅

🔥 EXIT STATUS 🔥

Because aria2 can handle multiple downloads at once, it encounters lots of errors in a session (living that chaotic main character life 😭). aria2 returns the following exit status based on the last error encountered.

0 — If all downloads were successful. 🎉
1 — If an unknown error occurred.
2 — If time out occurred.
3 — If a resource was not found.
4 — If aria2 saw the specified number of "resource not found" error. See --max-file-not-found option.
5 — If a download aborted because download speed was too slow. See --lowest-speed-limit option.
6 — If network problem occurred.
7 — If there were unfinished downloads. This error is only reported if all finished downloads were successful and there were unfinished downloads in a queue when aria2 exited by pressing Ctrl-C by an user or sending TERM or INT signal.
8 — If remote server did not support resume when resume was required to complete download.
9 — If there was not enough disk space available.
10 — If piece length was different from one in .aria2 control file. See --allow-piece-length-change option.
11 — If aria2 was downloading same file at that moment.
12 — If aria2 was downloading same info hash torrent at that moment.
13 — If file already existed. See --allow-overwrite option.
14 — If renaming file failed. See --auto-file-renaming option.
15 — If aria2 could not open existing file.
16 — If aria2 could not create new file or truncate existing file.
17 — If file I/O error occurred.
18 — If aria2 could not create directory.
19 — If name resolution failed.
20 — If aria2 could not parse Metalink document.
21 — If FTP command failed.
22 — If HTTP response header was bad or unexpected.
23 — If too many redirects occurred.
24 — If HTTP authorization failed.
25 — If aria2 could not parse bencoded file (usually .torrent file).
26 — If .torrent file was corrupted or missing information that aria2 needed.
27 — If Magnet URI was bad.
28 — If bad/unrecognized option was given or unexpected option argument was given.
29 — If the remote server was unable to handle the request due to a temporary overloading or maintenance.
30 — If aria2 could not parse JSON-RPC request.
31 — Reserved. Not used.
32 — If checksum validation failed.

NOTE: an error occurred in a finished download will not be reported as exit status. so don't come for her about it 😌

🌸 ENVIRONMENT 🌸

aria2 recognizes the following environment variables. put them in your shell rc and never think about them again bestie ✨

http_proxy [http://][USER:PASSWORD@]HOST[:PORT] — Specify proxy server for use in HTTP. Overrides http-proxy value in configuration file. The command-line option --http-proxy overrides this value.
https_proxy [http://][USER:PASSWORD@]HOST[:PORT] — Specify proxy server for use in HTTPS. Overrides https-proxy value in configuration file. The command-line option --https-proxy overrides this value.
ftp_proxy [http://][USER:PASSWORD@]HOST[:PORT] — Specify proxy server for use in FTP. Overrides ftp-proxy value in configuration file. The command-line option --ftp-proxy overrides this value.
all_proxy [http://][USER:PASSWORD@]HOST[:PORT] — Specify proxy server for use if no protocol-specific proxy is specified. Overrides all-proxy value in configuration file. The command-line option --all-proxy overrides this value.

NOTE: although aria2 accepts ftp:// and https:// scheme in proxy URI, it simply assumes that http:// is specified and does not change its behavior based on the specified scheme. she's got one vibe and she's sticking to it 💀

no_proxy [DOMAIN,...] — Specify a comma-separated list of host names, domains and network addresses with or without a subnet mask where no proxy should be used. Overrides the no-proxy value in configuration file. The command-line option --no-proxy overrides this value.

📁 FILES 📁

🌸 aria2.conf

okay so by default aria2 goes looking for its config in the legacy spot first: if $HOME/.aria2/aria2.conf is there, that's the one it uses. If it's not there, it parses $XDG_CONFIG_HOME/aria2/aria2.conf as the config file instead. You can point it wherever you want with the --conf-path option. And if you're in your no-config era? Use --no-conf. 💅

The config file is just a text file, one option per line, and each line is a NAME=VALUE pair where name is the long command-line option name with the -- prefix stripped off. Same syntax works for command-line options too, btw. Any line starting with # is a comment:

# sample configuration file for aria2c
listen-port=60000
dht-listen-port=60000
seed-ratio=1.0
max-upload-limit=50K
ftp-pasv=true

NOTE: bestie, your user/password and other confidential info might literally be sitting in this file. It is recommended to change the file mode bits of the config file (like, chmod 600 aria2.conf) so nobody else can peek at your contents. 🔒

Environment variables like ${HOME} get expanded by the shell, which means variables written inside the config file do not get expanded by the shell. BUT — and this is the cute part — it's genuinely useful to write ${HOME} in the config file when you're specifying file paths, so aria2 itself expands ${HOME} found in the following option values into your home directory:

ca-certificate
certificate
dht-file-path
dht-file-path6
dir
input-file
load-cookies
log
metalink-file
netrc-path
on-bt-download-complete
on-download-complete
on-download-error
on-download-start
on-download-stop
on-download-pause
out
private-key
rpc-certificate
rpc-private-key
save-cookies
save-session
server-stat-if
server-stat-of
torrent-file

⚠️ Heads up: this expansion happens even if you use those options on the command-line. Which means expansion can happen twice — first the shell, then aria2c. Double the vibes, double the carefulness.

🦋 dht.dat

Unless the legacy paths $HOME/.aria2/dht.dat and $HOME/.aria2/dht6.dat are already pointing at existing files, the IPv4 DHT routing table gets saved to $XDG_CACHE_HOME/aria2/dht.dat and the IPv6 DHT routing table gets saved to $XDG_CACHE_HOME/aria2/dht6.dat. 🗺️

💜 Netrc

Netrc support is on by default for HTTP(S)/FTP/SFTP. Wanna turn it off? Pass --no-netrc. Your .netrc file should have the correct permissions (600), no cap. 🔐

If the machine name starts with ., aria2 does a domain-match instead of an exact match — that's an aria2 extension, not standard. Example of a domain match, imagine this .netrc entry:

machine .example.org login myid password mypasswd

So aria2.example.org domain-matches .example.org and uses myid and mypasswd. ✨

Some more domain-match examples so you're not confused: example.net does not domain-match .example.org. And example.org does not domain-match .example.org because of that leading .. If you want to match example.org, then just write example.org. Periodt. 💅

🎀 Control File

aria2 keeps a control file to track download progress. It lives in the same directory as the file you're downloading, and its name is the downloading file's name with .aria2 stuck on the end. So if you're downloading file.zip, the control file is file.zip.aria2. 🫶

(One exception to this naming convention: if you're downloading a multi torrent, the control file is the "top directory" name of the torrent with .aria2 appended. That "top directory" name is the value of the "name" key in the "info" directory in a torrent file.)

Usually the control file gets deleted once the download finishes. And if aria2 decides the download can't be resumed (like, downloading from a HTTP server that doesn't support resume), no control file gets created at all. 😭

Normally if you lose a control file, you can't resume. BUT if you have a torrent or metalink with chunk checksums for the file, you can resume without a control file by giving the -V option to aria2c on the command-line. Slay. 🔥

🌈 Input File

The input file can hold a list of URIs for aria2 to download. And you can specify multiple URIs for a single entity — just separate them on a single line using the TAB character.

Each line is treated like it was given as a command-line argument, so they're affected by --force-sequential and --parameterized-uri.

Since URIs in the input file are read directly by aria2, they must not be quoted with single (') or double (") quotation marks. 🙈

Lines starting with # are comments and get skipped.

Bonus: after each line of URIs you can specify the following options. These optional lines must start with white space(s):

all-proxy
all-proxy-passwd
all-proxy-user
allow-overwrite
allow-piece-length-change
always-resume
async-dns
auto-file-renaming
bt-enable-hook-after-hash-check
bt-enable-lpd
bt-exclude-tracker
bt-external-ip
bt-force-encryption
bt-hash-check-seed
bt-load-saved-metadata
bt-max-peers
bt-metadata-only
bt-min-crypto-level
bt-prioritize-piece
bt-remove-unselected-file
bt-request-peer-speed-limit
bt-require-crypto
bt-save-metadata
bt-seed-unverified
bt-stop-timeout
bt-tracker
bt-tracker-connect-timeout
bt-tracker-interval
bt-tracker-timeout
check-integrity
checksum
conditional-get
connect-timeout
content-disposition-default-utf8
continue
dir
dry-run
enable-http-keep-alive
enable-http-pipelining
enable-mmap
enable-peer-exchange
file-allocation
follow-metalink
follow-torrent
force-save
ftp-passwd
ftp-pasv
ftp-proxy
ftp-proxy-passwd
ftp-proxy-user
ftp-reuse-connection
ftp-type
ftp-user
gid
hash-check-only
header
http-accept-gzip
http-auth-challenge
http-no-cache
http-passwd
http-proxy
http-proxy-passwd
http-proxy-user
http-user
https-proxy
https-proxy-passwd
https-proxy-user
index-out
lowest-speed-limit
max-connection-per-server
max-download-limit
max-file-not-found
max-mmap-limit
max-resume-failure-tries
max-tries
max-upload-limit
metalink-base-uri
metalink-enable-unique-protocol
metalink-language
metalink-location
metalink-os
metalink-preferred-protocol
metalink-version
min-split-size
no-file-allocation-limit
no-netrc
no-proxy
out
parameterized-uri
pause
pause-metadata
piece-length
proxy-method
realtime-chunk-checksum
referer
remote-time
remove-control-file
retry-wait
reuse-uri
rpc-save-upload-metadata
seed-ratio
seed-time
select-file
split
ssh-host-key-md
stream-piece-selector
timeout
uri-selector
use-head
user-agent

These options mean exactly the same thing as the command-line versions, they just apply to the URIs they belong to. But pls note: for options in the input file, the -- prefix must be stripped off. 🧚

Example time! Say the content of uri.txt is:

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

If aria2 runs with -i uri.txt -d /tmp options, then file.iso gets saved as /iso_images/file.img and it's downloaded from http://server/file.iso and http://mirror/file.iso. And bar is downloaded from http://foo/bar and saved as /tmp/bar. 💖

In some cases, the out parameter has no effect — see the note on the --out option for those restrictions.

⭐ Server Performance Profile ⭐

This section is all about the format of the server performance profile. The file is plain text and every line has several NAME=VALUE pairs separated by commas. Currently these NAMEs are recognized:

host — Host name of the server. Required.
protocol — Protocol for this profile, like ftp, http. Required.
dl_speed — The average download speed observed in the previous download, in bytes per sec. Required.
sc_avg_speed — The average download speed observed in the previous download, in bytes per sec. This value is only updated if the download was done in a single connection environment and is only used by AdaptiveURISelector. Optional.
mc_avg_speed — The average download speed observed in the previous download, in bytes per sec. This value is only updated if the download was done in a multi connection environment and is only used by AdaptiveURISelector. Optional.
counter — How many times the server is used. Currently this value is only used by AdaptiveURISelector. Optional.
last_updated — Last contact time in GMT with this server, specified in seconds since the Epoch (00:00:00 on January 1, 1970, UTC). Required.
status — ERROR is set when the server can't be reached, or is out-of-service, or a timeout occurred. Otherwise, OK is set.

Those fields all have to exist on one line. The order of fields doesn't matter, and you can put pairs other than the ones above — they're just simply ignored. 💀

An example follows:

host=localhost, protocol=http, dl_speed=32000, last_updated=1222491640, status=OK
host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR

🛰️ RPC INTERFACE 🛰️

aria2 serves up JSON-RPC over HTTP and XML-RPC over HTTP interfaces that basically do the same stuff. It also provides JSON-RPC over WebSocket. That one uses the exact same method signatures and response format as JSON-RPC over HTTP, but on top of that it also gives you server-initiated notifications. See the JSON-RPC over WebSocket section for more. 👑

okay so the request path for the JSON-RPC interface — and this is true for BOTH the HTTP version and the WebSocket version, bestie, they share — is /jsonrpc. 🫶 The XML-RPC interface lives at /rpc, its own lil address.

The WebSocket URI for JSON-RPC over WebSocket is ws://HOST:PORT/jsonrpc. And if you flipped on SSL/TLS encryption? Then it's wss://HOST:PORT/jsonrpc instead. 💅 (just swap the ws for wss, that's the whole vibe)

The JSON-RPC we implemented is based on JSON-RPC 2.0 <http://jsonrpc.org/specification>, and it supports HTTP POST and GET (that's the JSONP situation). The WebSocket transport? That's an aria2 extension, so it's our little thing. ✨

Now listen: the JSON-RPC interface does not support notifications over HTTP. But the RPC server will send notifications over WebSocket. It also does not support floating point numbers. And the character encoding must be UTF-8. No exceptions, no cap. 💀

When you're reading the JSON-RPC docs that follow, interpret structs as JSON objects. (struct = JSON object, that's the translation, periodt.)

🌸 Terminology 🌸

💖 GID 💖

The GID (or gid) is a key to manage each download. Every single download gets assigned a unique GID. Inside aria2, the GID is stored as a 64-bit binary value. For RPC access though, it's represented as a hex string of 16 characters — like 2089b05ecca3d829. 👑

Normally, aria2 generates this GID for each download, but you can specify GIDs manually using the --gid option. And here's the cute part: when you're querying downloads by GID, you can specify only the prefix of a GID — as long as that prefix is unique among the others. Short-king GIDs, we love to see it. 🦋

🔐 RPC authorization secret token 🔐

As of 1.18.4, in addition to HTTP basic authorization, aria2 provides RPC method-level authorization. And heads up, bestie: in a future release, HTTP basic authorization will be removed and RPC method-level authorization will become mandatory. 👀 So get comfy with it now.

To use RPC method-level authorization, you have to specify an RPC secret authorization token using the --rpc-secret option. For each RPC method call, the caller has to include the token prefixed with token:. And even when the --rpc-secret option is not used — if the first parameter in the RPC method is a string and starts with token:, it will be removed from the parameter list before the request is being processed. 🧚

For example, if the RPC secret authorization token is $$secret$$, calling the aria2.addUri RPC method would have to look like this:

aria2.addUri("token:$$secret$$", ["http://example.org/file"])

The system.multicall RPC method is treated specially. Since the XML-RPC specification only allows a single array as a parameter for this method, we don't specify the token in the call. Instead, each nested method call has to provide the token as the first parameter as described above. 🎀

NOTE: The secret token validation in aria2 is designed to take at least a certain amount of time to mitigate brute-force/dictionary attacks against the RPC interface. So it's recommended to prefer Batch or system.multicall requests when appropriate. (protect the vibes, protect the token 🛡️) system.listMethods and system.listNotifications can be executed without token. Since they just return available methods/notifications, they do not alter anything — they're safe without a secret token. 🫶

✨ Methods ✨

All the code examples are compatible with the Python 2.7 interpreter. For info on the secret parameter, go peek at RPC authorization secret token up above. ⬆️

🌈 `aria2.addUri([secret], uris[, options[, position]])`

This method adds a new download. uris is an array of HTTP/FTP/SFTP/BitTorrent URIs (strings) pointing to the same resource. And listen — if you mix URIs pointing to different resources, then the download may fail or be corrupted without aria2 complaining. It won't warn you, it'll just quietly do the wrong thing. 🙈 So don't do that.

When adding BitTorrent Magnet URIs, uris must have only one element, and it should be a BitTorrent Magnet URI. options is a struct and its members are pairs of option name and value. See Options below for more details. If position is given, it must be an integer starting from 0. The new download will be inserted at position in the waiting queue. If position is omitted, or position is larger than the current size of the queue, the new download is appended to the end of the queue. 💅

This method returns the GID of the newly registered download. 🎉

JSON-RPC Example

The following example adds http://example.org/file:

>>> import urllib2, json
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.addUri',
...                       'params':[['http://example.org/file']]})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> c.read()
'{"id":"qwer","jsonrpc":"2.0","result":"2089b05ecca3d829"}'

XML-RPC Example

The following example adds http://example.org/file:

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.addUri(['http://example.org/file'])
'2089b05ecca3d829'

The following example adds a new download with two sources and some options:

>>> s.aria2.addUri(['http://example.org/file', 'http://mirror/file'],
                    dict(dir="/tmp"))
'd2703803b52216d1'

The following example adds a download and inserts it to the front of the queue:

>>> s.aria2.addUri(['http://example.org/file'], {}, 0)
'ca3d829cee549a4d'

🦋 `aria2.addTorrent([secret], torrent[, uris[, options[, position]]])`

This method adds a BitTorrent download by uploading a ".torrent" file. If you wanna add a BitTorrent Magnet URI, use the aria2.addUri() method instead. torrent must be a base64-encoded string containing the contents of the ".torrent" file. 🧚

uris is an array of URIs (string). uris is used for Web-seeding. For single file torrents, the URI can be a complete URI pointing to the resource; if the URI ends with /, name in the torrent file is added. For multi-file torrents, name and path in the torrent are added to form a URI for each file. options is a struct and its members are pairs of option name and value. See Options below for more details. If position is given, it must be an integer starting from 0. The new download will be inserted at position in the waiting queue. If position is omitted, or position is larger than the current size of the queue, the new download is appended to the end of the queue. This method returns the GID of the newly registered download. ⭐

If --rpc-save-upload-metadata is true, the uploaded data is saved as a file named as the hex string of the SHA-1 hash of the data plus ".torrent" in the directory specified by the --dir option. E.g. a file name might be 0a3893293e27ac0490424c06de4d09242215f0a6.torrent. And if a file with the same name already exists — it is overwritten! 😭

If the file cannot be saved successfully, or --rpc-save-upload-metadata is false, the downloads added by this method are not saved by --save-session.

The following examples add the local file file.torrent.

JSON-RPC Example

>>> import urllib2, json, base64
>>> torrent = base64.b64encode(open('file.torrent').read())
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'asdf',
...                       'method':'aria2.addTorrent', 'params':[torrent]})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> c.read()
'{"id":"asdf","jsonrpc":"2.0","result":"2089b05ecca3d829"}'

XML-RPC Example

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent', mode='rb').read()))
'2089b05ecca3d829'

🎀 `aria2.addMetalink([secret], metalink[, options[, position]])`

This method adds a Metalink download by uploading a ".metalink" file. metalink is a base64-encoded string which contains the contents of the ".metalink" file. options is a struct and its members are pairs of option name and value. See Options below for more details. If position is given, it must be an integer starting from 0. The new download will be inserted at position in the waiting queue. If position is omitted, or position is larger than the current size of the queue, the new download is appended to the end of the queue. 💜

This method returns an array of GIDs of newly registered downloads. (yes, plural, it can spawn a whole squad 👑)

If --rpc-save-upload-metadata is true, the uploaded data is saved as a file named hex string of SHA-1 hash of the data plus ".metalink" in the directory specified by the --dir option. E.g. a file name might be 0a3893293e27ac0490424c06de4d09242215f0a6.metalink. And if a file with the same name already exists — it is overwritten! 😭

If the file cannot be saved successfully, or --rpc-save-upload-metadata is false, the downloads added by this method are not saved by --save-session.

The following examples add the local file file.meta4.

JSON-RPC Example

>>> import urllib2, json, base64
>>> metalink = base64.b64encode(open('file.meta4').read())
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.addMetalink',
...                       'params':[metalink]})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> c.read()
'{"id":"qwer","jsonrpc":"2.0","result":["2089b05ecca3d829"]}'

XML-RPC Example

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.addMetalink(xmlrpclib.Binary(open('file.meta4', mode='rb').read()))
['2089b05ecca3d829']

💅 `aria2.remove([secret], gid)`

This method removes the download denoted by gid (string). If the specified download is in progress, it is first stopped. The status of the removed download becomes removed. This method returns the GID of the removed download. 🫶

The following examples remove a download with GID 2089b05ecca3d829.

JSON-RPC Example

>>> import urllib2, json
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.remove',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> c.read()
'{"id":"qwer","jsonrpc":"2.0","result":"2089b05ecca3d829"}'

XML-RPC Example

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.remove('2089b05ecca3d829')
'2089b05ecca3d829'

💅 `aria2.forceRemove([secret], gid)`

okay so this one removes the download with the gid you hand it, and it works exactly like aria2.remove() except — and this is the whole point — it does the removal without doing any of the slow stuff first, like contacting BitTorrent trackers to unregister the download. so it's the instant version, no waiting around. 🔥

🛑 `aria2.pause([secret], gid)`

pauses the download with that gid (it's a string, bestie). the status of a paused download becomes paused. if the download was active, it gets bumped to the front of the waiting queue — yes, it cuts the line, main character energy fr. while the status is paused, the download is not started. wanna flip it back to waiting? use the aria2.unpause() method. and this method returns the GID of the paused download. ✨

🫶 `aria2.pauseAll([secret])`

this is literally the same as calling aria2.pause() for every single active/waiting download. and it returns OK. that's it, that's the method. 💖

💥 `aria2.forcePause([secret], gid)`

pauses the download with that gid, and it behaves just like aria2.pause() except it skips all the actions that take time — like contacting BitTorrent trackers to unregister the download first. so, pause but make it fast. ⚡

💥 `aria2.forcePauseAll([secret])`

same as calling aria2.forcePause() for every active/waiting download. returns OK. slay. 🎀

▶️ `aria2.unpause([secret], gid)`

this flips the status of the download with that gid (string!) from paused to waiting, which makes the download eligible to be restarted. it returns the GID of the unpaused download. we love a comeback arc. 🦋

🌈 `aria2.unpauseAll([secret])`

same as calling aria2.unpause() for every paused download. returns OK. group un-pause, iconic. 👑

🔍 `aria2.tellStatus([secret], gid[, keys])`

this returns the progress of the download denoted by gid (a string, keep up). keys is an array of strings — if you specify it, the response contains only the keys in the keys array. if keys is empty or omitted, you get every key. this is highkey useful when you just want specific keys and wanna avoid unnecessary transfers.

for example, aria2.tellStatus("2089b05ecca3d829", ["gid", "status"]) returns the gid and status keys only. periodt. ✨

the response is a struct and contains the following keys. values are strings. 💜

gid — GID of the download.
status — active for currently downloading/seeding downloads. waiting for downloads in the queue; download is not started. paused for paused downloads. error for downloads that were stopped because of error. complete for stopped and completed downloads. removed for the downloads removed by user.
totalLength — total length of the download in bytes.
completedLength — completed length of the download in bytes.
uploadLength — uploaded length of the download in bytes.
bitfield — hexadecimal representation of the download progress. the highest bit corresponds to the piece at index 0. any set bits indicate loaded pieces, while unset bits indicate not yet loaded and/or missing pieces. any overflow bits at the end are set to zero. when the download was not started yet, this key will not be included in the response.
downloadSpeed — download speed of this download, measured in bytes/sec.
uploadSpeed — upload speed of this download, measured in bytes/sec.
infoHash — InfoHash. BitTorrent only.
numSeeders — the number of seeders aria2 has connected to. BitTorrent only.
seeder — true if the local endpoint is a seeder. otherwise false. BitTorrent only.
pieceLength — piece length in bytes.
numPieces — the number of pieces.
connections — the number of peers/servers aria2 has connected to.
errorCode — the code of the last error for this item, if any. the value is a string. the error codes are defined in the EXIT STATUS section. this value is only available for stopped/completed downloads.
errorMessage — the (hopefully) human readable error message associated to errorCode.
followedBy — list of GIDs which are generated as the result of this download. for example, when aria2 downloads a Metalink file, it generates downloads described in the Metalink (see the --follow-metalink option). this value is useful to track auto-generated downloads. if there are no such downloads, this key will not be included in the response.
following — the reverse link for followedBy. a download included in followedBy has this object's GID in its following value.
belongsTo — GID of a parent download. some downloads are a part of another download. for example, if a file in a Metalink has BitTorrent resources, the downloads of .torrent files are parts of that parent. if this download has no parent, this key will not be included in the response.
dir — directory to save files.
files — returns the list of files. the elements of this list are the same structs used in the aria2.getFiles() method.
bittorrent — struct which contains information retrieved from the .torrent (file). BitTorrent only. it contains the following keys:
- announceList — list of lists of announce URIs. if the torrent contains announce and no announce-list, announce is converted to the announce-list format.
- comment — the comment of the torrent. comment.utf-8 is used if available.
- creationDate — the creation time of the torrent. the value is an integer since the epoch, measured in seconds.
- mode — file mode of the torrent. the value is either single or multi.
- info — struct which contains data from the Info dictionary. it contains the following keys:
  - name — name in the info dictionary. name.utf-8 is used if available.
verifiedLength — the number of verified number of bytes while the files are being hash checked. this key exists only when this download is being hash checked.
verifyIntegrityPending — true if this download is waiting for the hash check in a queue. this key exists only when this download is in the queue.

🐍 JSON-RPC Example

the following example gets information about a download with GID#2089b05ecca3d829:

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.tellStatus',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': {u'bitfield': u'0000000000',
             u'completedLength': u'901120',
             u'connections': u'1',
             u'dir': u'/downloads',
             u'downloadSpeed': u'15158',
             u'files': [{u'index': u'1',
                         u'length': u'34896138',
                         u'completedLength': u'34896138',
                         u'path': u'/downloads/file',
                         u'selected': u'true',
                         u'uris': [{u'status': u'used',
                                    u'uri': u'http://example.org/file'}]}],
             u'gid': u'2089b05ecca3d829',
             u'numPieces': u'34',
             u'pieceLength': u'1048576',
             u'status': u'active',
             u'totalLength': u'34896138',
             u'uploadLength': u'0',
             u'uploadSpeed': u'0'}}

the following example gets only specific keys:

>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.tellStatus',
...                       'params':['2089b05ecca3d829',
...                                 ['gid',
...                                  'totalLength',
...                                  'completedLength']]})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': {u'completedLength': u'5701632',
             u'gid': u'2089b05ecca3d829',
             u'totalLength': u'34896138'}}

🐍 XML-RPC Example

the following example gets information about a download with GID#2089b05ecca3d829:

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.tellStatus('2089b05ecca3d829')
>>> pprint(r)
{'bitfield': 'ffff80',
 'completedLength': '34896138',
 'connections': '0',
 'dir': '/downloads',
 'downloadSpeed': '0',
 'errorCode': '0',
 'files': [{'index': '1',
            'length': '34896138',
            'completedLength': '34896138',
            'path': '/downloads/file',
            'selected': 'true',
            'uris': [{'status': 'used',
                      'uri': 'http://example.org/file'}]}],
 'gid': '2089b05ecca3d829',
 'numPieces': '17',
 'pieceLength': '2097152',
 'status': 'complete',
 'totalLength': '34896138',
 'uploadLength': '0',
 'uploadSpeed': '0'}

okay and if you only want some of the keys and not the whole entire buffet, you just pass the ones you want as a list — watch:

The following example gets only specific keys:

>>> r = s.aria2.tellStatus('2089b05ecca3d829', ['gid', 'totalLength', 'completedLength'])
>>> pprint(r)
{'completedLength': '34896138', 'gid': '2089b05ecca3d829', 'totalLength': '34896138'}

see? chef's kiss. you asked for three things, you got three things. 💅

🦋 `aria2.getUris([secret], gid)` 🦋

bestie this one hands you back the URIs that the download with that gid (a string, always a string) is working with. the response is an array of structs, and every value inside is a string. each struct has these keys:

uri — the URI itself. literally the address. 🌐
status — 'used' if the URI is currently in use. 'waiting' if the URI is still chilling in the queue, not called up yet.

JSON-RPC Example

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getUris',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': [{u'status': u'used',
              u'uri': u'http://example.org/file'}]}

XML-RPC Example

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getUris('2089b05ecca3d829')
>>> pprint(r)
[{'status': 'used', 'uri': 'http://example.org/file'}]

🎀 `aria2.getFiles([secret], gid)` 🎀

this one gives you the file list for the download with that gid (string). you get back an array of structs, and again, the values are strings. the keys are:

index — the index of the file, starting at 1, in the same order the files appear in the multi-file torrent. no zero-indexing here, we're not animals. 🔢
path — the file path. where it lives. 🏠
length — file size in bytes.
completedLength — how many bytes of this file are done. ⚠️ okay important heads up: it is possible that the sum of completedLength is less than the completedLength that aria2.tellStatus() hands back. why? because completedLength in aria2.getFiles() only counts completed pieces. meanwhile completedLength in aria2.tellStatus() also counts partially completed pieces. so like, same name, different vibe. don't get got. 💀
selected — true if this file is selected by the --select-file option. if --select-file isn't specified, OR this is a single-file torrent, OR it's not a torrent download at all, then this value is always true. otherwise it's false.
uris — a list of URIs for this file. the element type is the exact same struct used in the aria2.getUris() method (so uri + status, you already know the drill).

JSON-RPC Example

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getFiles',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': [{u'index': u'1',
              u'length': u'34896138',
              u'completedLength': u'34896138',
              u'path': u'/downloads/file',
              u'selected': u'true',
              u'uris': [{u'status': u'used',
                         u'uri': u'http://example.org/file'}]}]}

XML-RPC Example

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getFiles('2089b05ecca3d829')
>>> pprint(r)
[{'index': '1',
  'length': '34896138',
  'completedLength': '34896138',
  'path': '/downloads/file',
  'selected': 'true',
  'uris': [{'status': 'used',
            'uri': 'http://example.org/file'}]}]

👑 `aria2.getPeers([secret], gid)` 👑

okay so this one returns a list of peers for the download with that gid (string). ⚠️ BitTorrent only — if you're not doing torrent stuff, this is not your moment. the response is an array of structs with these keys, values are strings:

peerId — the peer ID, percent-encoded. 🆔
ip — the IP address of the peer.
port — the port number of the peer.
bitfield — hex representation of that peer's download progress. the highest bit corresponds to the piece at index 0. set bits mean the piece is available, unset bits mean the piece is missing. any spare bits at the end get set to zero.
amChoking — true if aria2 is choking the peer. otherwise false. (yes it's giving toxic but it's just protocol bestie 🫶)
peerChoking — true if the peer is choking aria2. otherwise false.
downloadSpeed — download speed (byte/sec) that this client gets from the peer. 📥
uploadSpeed — upload speed (byte/sec) that this client uploads to the peer. 📤
seeder — true if this peer is a seeder. otherwise false. 🌱

JSON-RPC Example

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getPeers',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': [{u'amChoking': u'true',
              u'bitfield': u'ffffffffffffffffffffffffffffffffffffffff',
              u'downloadSpeed': u'10602',
              u'ip': u'10.0.0.9',
              u'peerChoking': u'false',
              u'peerId': u'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6',
              u'port': u'6881',
              u'seeder': u'true',
              u'uploadSpeed': u'0'},
             {u'amChoking': u'false',
              u'bitfield': u'ffffeff0fffffffbfffffff9fffffcfff7f4ffff',
              u'downloadSpeed': u'8654',
              u'ip': u'10.0.0.30',
              u'peerChoking': u'false',
              u'peerId': u'bittorrent client758',
              u'port': u'37842',
              u'seeder': u'false',
              u'uploadSpeed': u'6890'}]}

XML-RPC Example

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getPeers('2089b05ecca3d829')
>>> pprint(r)
[{'amChoking': 'true',
  'bitfield': 'ffffffffffffffffffffffffffffffffffffffff',
  'downloadSpeed': '10602',
  'ip': '10.0.0.9',
  'peerChoking': 'false',
  'peerId': 'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6',
  'port': '6881',
  'seeder': 'true',
  'uploadSpeed': '0'},
 {'amChoking': 'false',
  'bitfield': 'ffffeff0fffffffbfffffff9fffffcfff7f4ffff',
  'downloadSpeed': '8654',
  'ip': '10.0.0.30',
  'peerChoking': 'false',
  'peerId': 'bittorrent client758',
  'port': '37842',
  'seeder': 'false,
  'uploadSpeed': '6890'}]

🌈 `aria2.getServers([secret], gid)` 🌈

and finally for this batch — this one returns the currently connected HTTP(S)/FTP/SFTP servers for the download with that gid (string). response is an array of structs, values are strings, keys go like this:

index — the index of the file, starting at 1, in the same order the files appear in the multi-file metalink. 🔢
servers — a list of structs that contain the following keys:
- uri — the original URI. 🧭
- currentUri — the URI currently being used for downloading. heads up: if redirection is involved, currentUri and uri may differ. so don't assume they're the same bestie, that's how you get confused.
- downloadSpeed — download speed (byte/sec). ⚡

JSON-RPC Example

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getServers',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': [{u'index': u'1',
              u'servers': [{u'currentUri': u'http://example.org/file',
                            u'downloadSpeed': u'10467',
                            u'uri': u'http://example.org/file'}]}]}

XML-RPC Example

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getServers('2089b05ecca3d829')
>>> pprint(r)
[{'index': '1',
  'servers': [{'currentUri': 'http://example.org/dl/file',
               'downloadSpeed': '20285',
               'uri': 'http://example.org/file'}]}]

and that output? chef's kiss, the servers list is giving exactly what you asked for 💅

aria2.tellActive([secret][, keys])

okay so this one hands you back a list of active downloads ✨ The response is an array of the exact same structs that aria2.tellStatus() returns — same shape, no surprises. And for the keys parameter? Bestie, go read the aria2.tellStatus() method, it's all explained there 🫶

aria2.tellWaiting([secret], offset, num[, keys])

this returns a list of waiting downloads — including paused ones 👀 offset is an integer and it specifies the offset from the download waiting at the front. num is an integer and it specifies the max. number of downloads to be returned. And keys? Again, aria2.tellStatus() method, go look 🔍

If offset is a positive integer, this method returns downloads in the range of [offset, offset + num).

But here's where it gets spicy 🔥 — offset can be a negative integer. offset == -1 points last download in the waiting queue and offset == -2 points the download before the last download, and so on. Downloads in the response are in reversed order then. Iconic behaviour tbh.

For example, imagine three downloads "A", "B" and "C" are waiting in this order.

aria2.tellWaiting(0, 1) returns ["A"].
aria2.tellWaiting(1, 2) returns ["B", "C"].
aria2.tellWaiting(-1, 2) returns ["C", "B"].

The response is an array of the same structs as returned by aria2.tellStatus() method.

aria2.tellStopped([secret], offset, num[, keys])

list of stopped downloads coming right up 🍓 offset is an integer and it specifies the offset from the least recently stopped download. num is an integer and it specifies the max. number of downloads to be returned. For the keys parameter, please refer to the aria2.tellStatus() method (you know the drill by now, bestie 💜).

offset and num have the same semantics as described in the aria2.tellWaiting() method.

The response is an array of the same structs as returned by the aria2.tellStatus() method.

aria2.changePosition([secret], gid, pos, how)

this method changes the position of the download denoted by gid in the queue 🎯 pos is an integer. how is a string. And the how values are:

If how is POS_SET, it moves the download to a position relative to the beginning of the queue.
If how is POS_CUR, it moves the download to a position relative to the current position.
If how is POS_END, it moves the download to a position relative to the end of the queue.

If the destination position is less than 0 or beyond the end of the queue, it moves the download to the beginning or the end of the queue respectively. The response is an integer denoting the resulting position 👑

For example, if GID#2089b05ecca3d829 is currently in position 3, aria2.changePosition('2089b05ecca3d829', -1, 'POS_CUR') will change its position to 2. Additionally aria2.changePosition('2089b05ecca3d829', 0, 'POS_SET') will change its position to 0 (the beginning of the queue).

The following examples move the download GID#2089b05ecca3d829 to the front of the queue.

JSON-RPC Example

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.changePosition',
...                       'params':['2089b05ecca3d829', 0, 'POS_SET']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': 0}

XML-RPC Example

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.changePosition('2089b05ecca3d829', 0, 'POS_SET')
0

aria2.changeUri([secret], gid, fileIndex, delUris, addUris[, position])

this method removes the URIs in delUris from and appends the URIs in addUris to download denoted by gid 🌸 delUris and addUris are lists of strings. A download can contain multiple files and URIs are attached to each file. fileIndex is used to select which file to remove/attach given URIs. fileIndex is 1-based. position is used to specify where URIs are inserted in the existing waiting URI list. position is 0-based. When position is omitted, URIs are appended to the back of the list.

bestie, listen: this method first executes the removal and then the addition. So position is the position after URIs are removed, not the position when this method is called. Don't get caught out 💀

When removing an URI, if the same URIs exist in download, only one of them is removed for each URI in delUris. In other words, if there are three URIs http://example.org/aria2 and you want remove them all, you have to specify (at least) 3 http://example.org/aria2 in delUris.

This method returns a list which contains two integers. The first integer is the number of URIs deleted. The second integer is the number of URIs added.

The following examples add the URI http://example.org/file to the file whose index is 1 and belongs to the download GID#2089b05ecca3d829.

JSON-RPC Example

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.changeUri',
...                       'params':['2089b05ecca3d829', 1, [],
...                                 ['http://example.org/file']]})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [0, 1]}

XML-RPC Example

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.changeUri('2089b05ecca3d829', 1, [],
                      ['http://example.org/file'])
[0, 1]

aria2.getOption([secret], gid)

gives you back the options of the download denoted by gid 🎀 The response is a struct where keys are the names of options. The values are strings.

heads up, no cap: this method does not return options which have no default value and have not been set on the command-line, in configuration files or RPC methods. So don't be shocked when something's missing 🙈

The following examples get options of the download GID#2089b05ecca3d829.

JSON-RPC Example

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getOption',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': {u'allow-overwrite': u'false',
             u'allow-piece-length-change': u'false',
             u'always-resume': u'true',
             u'async-dns': u'true',
...

XML-RPC Example

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getOption('2089b05ecca3d829')
>>> pprint(r)
{'allow-overwrite': 'false',
 'allow-piece-length-change': 'false',
 'always-resume': 'true',
 'async-dns': 'true',
 ....

aria2.changeOption([secret], gid, options)

this one changes options of the download denoted by gid (string) dynamically 💫 options is a struct. The options listed in Input File subsection are available, except for following options:

dry-run
metalink-base-uri
parameterized-uri
pause
piece-length
rpc-save-upload-metadata

Except for the following options, changing the other options of active download makes it restart (restart itself is managed by aria2, and no user intervention is required — so like, don't panic, she's got this 👑):

bt-max-peers
bt-request-peer-speed-limit
bt-remove-unselected-file
force-save
max-download-limit
max-upload-limit

This method returns OK for success.

The following examples set the max-download-limit option to 20K for the download GID#2089b05ecca3d829.

🫶 side note: the JSON-RPC example below literally shows 10K and the XML-RPC one shows 20K — that's just how the page has it, fr fr.

JSON-RPC Example

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.changeOption',
...                       'params':['2089b05ecca3d829',
...                                 {'max-download-limit':'10K'}]})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'}

XML-RPC Example

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.changeOption('2089b05ecca3d829', {'max-download-limit':'20K'})
'OK'

aria2.getGlobalOption([secret])

returns the global options 🌈 The response is a struct. Its keys are the names of options. Values are strings.

same energy as before, bestie: this method does not return options which have no default value and have not been set on the command-line, in configuration files or RPC methods.

Because global options are used as a template for the options of newly added downloads, the response contains keys returned by the aria2.getOption() method. cute, right? 🦋

aria2.changeGlobalOption([secret], options)

changes global options dynamically ✨ options is a struct. The following options are available:

bt-max-open-files
download-result
keep-unfinished-download-result
log
log-level
max-concurrent-downloads
max-download-result
max-overall-download-limit
max-overall-upload-limit
optimize-concurrent-downloads
save-cookies
save-session
server-stat-of

Plus, bestie, the options listed in the Input File subsection are also up for grabs — except for these five: checksum, index-out, out, pause and select-file. Not those. Hands off. 🙅‍♀️

And with the log option you can dynamically start logging or swap the log file mid-flight, which is iconic of it honestly. Wanna stop logging? Just pass an empty string ("") as the parameter value and it's done, no notes. But heads up: the log file is always opened in append mode — it never overwrites, it just keeps adding. This method returns OK when it works. ✨

aria2.getGlobalStat([secret])

This one gives you the global receipts — the overall download and upload speeds, all of it. The response is a struct, and it's got these keys. Values are strings, always strings, no cap.

downloadSpeed — overall download speed (byte/sec). 🏃‍♀️
uploadSpeed — overall upload speed (byte/sec).
numActive — how many downloads are active right now.
numWaiting — how many downloads are waiting.
numStopped — how many downloads stopped in the current session. This value is capped by the --max-download-result option.
numStoppedTotal — how many downloads stopped in the current session, and this one is NOT capped by the --max-download-result option. The truth, the whole truth. 💅

JSON-RPC Example

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getGlobalStat'})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': {u'downloadSpeed': u'21846',
             u'numActive': u'2',
             u'numStopped': u'0',
             u'numWaiting': u'0',
             u'uploadSpeed': u'0'}}

XML-RPC Example

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getGlobalStat()
>>> pprint(r)
{'downloadSpeed': '23136',
 'numActive': '2',
 'numStopped': '0',
 'numWaiting': '0',
 'uploadSpeed': '0'}

aria2.purgeDownloadResult([secret])

This one purges</purge> all those completed / error / removed downloads so you free up memory. Marie Kondo that download list. 🧹 This method returns OK.

aria2.removeDownloadResult([secret], gid)

Removes a single completed / error / removed download — the one denoted by gid — from memory. Returns OK for success. Bye girl, we won't miss you. 👋

The following examples remove the download result of the download GID 2089b05ecca3d829.

JSON-RPC Example

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.removeDownloadResult',
...                       'params':['2089b05ecca3d829']})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'}

XML-RPC Example

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.removeDownloadResult('2089b05ecca3d829')
'OK'

aria2.getVersion([secret])

Tells you the version of aria2 and the list of enabled features. Response is a struct with these keys:

version — version number of aria2, as a string.
enabledFeatures — list of enabled features. Each feature is given as a string.

JSON-RPC Example

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getVersion'})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': {u'enabledFeatures': [u'Async DNS',
                                  u'BitTorrent',
                                  u'Firefox3 Cookie',
                                  u'GZip',
                                  u'HTTPS',
                                  u'Message Digest',
                                  u'Metalink',
                                  u'XML-RPC'],
             u'version': u'1.11.0'}}

XML-RPC Example

>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getVersion()
>>> pprint(r)
{'enabledFeatures': ['Async DNS',
                     'BitTorrent',
                     'Firefox3 Cookie',
                     'GZip',
                     'HTTPS',
                     'Message Digest',
                     'Metalink',
                     'XML-RPC'],
 'version': '1.11.0'}

aria2.getSessionInfo([secret])

Returns session info. The response is a struct with this one key:

sessionId — the session ID, which is generated each time aria2 is invoked. Fresh every run, like a new manicure. 💅

JSON-RPC Example

>>> import urllib2, json
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'aria2.getSessionInfo'})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer',
 u'jsonrpc': u'2.0',
 u'result': {u'sessionId': u'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}}

XML-RPC Example

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.getSessionInfo()
{'sessionId': 'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}

aria2.shutdown([secret])

Shuts down aria2. That's it, that's the method. Returns OK. 😴

aria2.forceShutdown([secret])

Shuts down aria2(). This method behaves like :func:'aria2.shutdown` without performing any actions which take time, such as contacting BitTorrent trackers to unregister downloads first. So it's the no-thoughts-just-leave version. This method returns OK.

aria2.saveSession([secret])

Saves the current session to a file specified by the --save-session option. This method returns OK if it succeeds. Snapshot the whole vibe, bestie. 📸

system.multicall(methods)

This method encapsulates multiple method calls in a single request — bulk order, one delivery. ✨ methods is an array of structs. The structs contain two keys: methodName and params. methodName is the method name to call, and params is the array containing parameters for that method call. This method returns an array of responses. The elements will be either a one-item array containing the return value of the method call, or a struct of fault element if an encapsulated method call fails.

In the following examples, we add 2 downloads. The first one is http://example.org/file and the second one is file.torrent.

JSON-RPC Example

>>> import urllib2, json, base64
>>> from pprint import pprint
>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
...                       'method':'system.multicall',
...                       'params':[[{'methodName':'aria2.addUri',
...                                   'params':[['http://example.org']]},
...                                  {'methodName':'aria2.addTorrent',
...                                   'params':[base64.b64encode(open('file.torrent').read())]}]]})
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [[u'2089b05ecca3d829'], [u'd2703803b52216d1']]}

JSON-RPC additionally supports Batch requests as described in the JSON-RPC 2.0 Specification:

>>> jsonreq = json.dumps([{'jsonrpc':'2.0', 'id':'qwer',
...                        'method':'aria2.addUri',
...                        'params':[['http://example.org']]},
...                       {'jsonrpc':'2.0', 'id':'asdf',
...                        'method':'aria2.addTorrent',
...                        'params':[base64.b64encode(open('file.torrent').read())]}])
>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
>>> pprint(json.loads(c.read()))
[{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'2089b05ecca3d829'},
 {u'id': u'asdf', u'jsonrpc': u'2.0', u'result': u'd2703803b52216d1'}]

XML-RPC Example

>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> mc = xmlrpclib.MultiCall(s)
>>> mc.aria2.addUri(['http://example.org/file'])
>>> mc.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent', mode='rb').read()))
>>> r = mc()
>>> tuple(r)
('2089b05ecca3d829', 'd2703803b52216d1')

system.listMethods()

Returns all the available RPC methods in an array of string. And here's the slay part: unlike the other methods, this one does NOT require a secret token. That's safe, because this method literally just returns the available method names — it's not out here leaking anything. 🫶

JSON-RPC Example

                 >>> import urllib2, json
                 >>> from pprint import pprint
                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
                 ...                       'method':'system.listMethods'})
                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
                 >>> pprint(json.loads(c.read()))
                 {u'id': u'qwer',
                  u'jsonrpc': u'2.0',
                  u'result': [u'aria2.addUri',
                              u'aria2.addTorrent',
                 ...

and here's the same vibe but make it XML-RPC:

                 >>> import xmlrpclib
                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
                 >>> s.system.listMethods()
                 ['aria2.addUri', 'aria2.addTorrent', ...

💜 system.listNotifications() 💜

okay so this one hands you all the available RPC notifications, delivered as an array of string. And the plot twist? Unlike basically every other method, this one does not need a secret token. Which is fine, actually, because it literally just returns the names of the notifications that exist — nothing spicy, nothing private. safe queen behavior 🫶

✨ JSON-RPC Example ✨

                 >>> import urllib2, json
                 >>> from pprint import pprint
                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
                 ...                       'method':'system.listNotifications'})
                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
                 >>> pprint(json.loads(c.read()))
                 {u'id': u'qwer',
                  u'jsonrpc': u'2.0',
                  u'result': [u'aria2.onDownloadStart',
                              u'aria2.onDownloadPause',
                 ...

✨ XML-RPC Example ✨

                 >>> import xmlrpclib
                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
                 >>> s.system.listNotifications()
                 ['aria2.onDownloadStart', 'aria2.onDownloadPause', ...

😭 Error Handling 😭

so when things go sideways (and bestie, sometimes they do):

Over JSON-RPC, aria2 sends back a JSON object — the error code lives in code, and the error message lives in message.
Over XML-RPC, aria2 returns faultCode=1 and drops the error message into faultString.

🎀 Options 🎀

The same options as for --input-file are available. See the Input File subsection for the complete list — no skimming, go read it 👑

Inside the option struct:

name is the option name (without the -- in front, okay? it's giving minimal)
value is the argument, as a string

💅 JSON-RPC Example 💅

{'split':'1', 'http-proxy':'http://proxy/'}

💅 XML-RPC Example 💅

<struct>
  <member>
    <name>split</name>
    <value><string>1</string></value>
  </member>
  <member>
    <name>http-proxy</name>
    <value><string>http://proxy/</string></value>
  </member>
</struct>

okay so here's a lil ✨situation✨: the header and index-out options are allowed multiple times on the command-line. But since the name should be unique inside a struct — and many XML-RPC library implementations use a hash or dict for struct — a single string is just not enough. Not the move. To get around this limitation, you can use an array as the value, as well as a string. problem solved, slay 💅

💅 JSON-RPC Example 💅

{'header':['Accept-Language: ja', 'Accept-Charset: utf-8']}

💅 XML-RPC Example 💅

<struct>
  <member>
    <name>header</name>
    <value>
      <array>
        <data>
          <value><string>Accept-Language: ja</string></value>
          <value><string>Accept-Charset: utf-8</string></value>
        </data>
      </array>
    </value>
  </member>
</struct>

and here's a lil demo, bestie — it adds a download with two options: dir and header. The header option needs two values, so it uses a list:

    >>> import xmlrpclib
    >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
    >>> opts = dict(dir='/tmp',
    ...             header=['Accept-Language: ja',
    ...                     'Accept-Charset: utf-8'])
    >>> s.aria2.addUri(['http://example.org/file'], opts)
    '1'

🌈 JSON-RPC using HTTP GET 🌈

plot twist! The JSON-RPC interface also supports requests via HTTP GET. The encoding scheme in GET parameters is based on JSON-RPC over HTTP Specification [2008-1-15(RC1)]. The encoding of the GET parameters goes like this:

/jsonrpc?method=METHOD_NAME&id=ID&params=BASE64_ENCODED_PARAMS

The method and id are always treated as a JSON string, and their encoding must be UTF-8.

For example, the encoded string of aria2.tellStatus('2089b05ecca3d829') with id='foo' looks like this:

/jsonrpc?method=aria2.tellStatus&id=foo&params=WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D

The params parameter is a Base64-encoded JSON array, which usually shows up in the params attribute of the JSON-RPC request object. In the example above, the params is ["2089b05ecca3d829"], therefore:

["2089b05ecca3d829"] --(Base64)--> WyIyMDg5YjA1ZWNjYTNkODI5Il0=
             --(Percent Encode)--> WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D

and there's more ✨ The JSON-RPC interface also supports JSONP. You can specify the callback function in the jsoncallback parameter:

/jsonrpc?method=aria2.tellStatus&id=foo&params=WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D&jsoncallback=cb

⚠️ for Batch requests, the method and id parameters must not be specified. The whole request has to go in the params parameter. no exceptions, bestie.

For example, a Batch request:

[{'jsonrpc':'2.0', 'id':'qwer', 'method':'aria2.getVersion'},
 {'jsonrpc':'2.0', 'id':'asdf', 'method':'aria2.tellActive'}]

must be encoded like this:

/jsonrpc?params=W3sianNvbnJwYyI6ICIyLjAiLCAiaWQiOiAicXdlciIsICJtZXRob2QiOiAiYXJpYTIuZ2V0VmVyc2lvbiJ9LCB7Impzb25ycGMiOiAiMi4wIiwgImlkIjogImFzZGYiLCAibWV0aG9kIjogImFyaWEyLnRlbGxBY3RpdmUifV0%3D

🦋 JSON-RPC over WebSocket 🦋

JSON-RPC over WebSocket uses the same method signatures and response format as JSON-RPC over HTTP. The supported WebSocket version is 13, which is detailed in RFC 6455. iykyk 💜

To send an RPC request to the RPC server, send a serialized JSON string in a Text frame. The response from the RPC server is delivered also in a Text frame. clean, simple, iconic.

🔔 Notifications 🔔

The RPC server might send notifications to the client. Notifications are unidirectional, therefore the client that receives a notification must not respond to it. don't do it. it's not the vibe.

The method signature of a notification is much like a normal method request, but it lacks the id key. The value of the params key is the data this notification carries. The format of that value varies depending on the notification method. Following notification methods are defined:

`aria2.onDownloadStart(event)`

This notification gets sent when a download is started. The event is of type struct and it contains the following keys. The value type is string.

gid — GID of the download.

`aria2.onDownloadPause(event)`

This notification gets sent when a download is paused. The event is the same struct as the event argument of the aria2.onDownloadStart() method.

`aria2.onDownloadStop(event)`

This notification gets sent when a download is stopped by the user. The event is the same struct as the event argument of the aria2.onDownloadStart() method.

`aria2.onDownloadComplete(event)`

This notification gets sent when a download is complete. For BitTorrent downloads, this notification is sent when the download is complete and seeding is over. The event is the same struct of the event argument of the aria2.onDownloadStart() method.

`aria2.onDownloadError(event)`

This notification gets sent when a download is stopped due to an error. The event is the same struct as the event argument of the aria2.onDownloadStart() method.

`aria2.onBtDownloadComplete(event)`

This notification gets sent when a torrent download is complete but seeding is still going on. The event is the same struct as the event argument of the aria2.onDownloadStart() method.

🧚 Sample XML-RPC Client Code 🧚

okay bestie, real code time. The following Ruby script adds http://localhost/aria2.tar.bz2 to aria2c (running on localhost) with the option --dir=/downloads and prints the RPC response:

#!/usr/bin/env ruby

require 'xmlrpc/client'
require 'pp'

client=XMLRPC::Client.new2("http://localhost:6800/rpc")

options={ "dir" => "/downloads" }
result=client.call("aria2.addUri", [ "http://localhost/aria2.tar.bz2" ], options)

pp result

If you are a Python lover, you can use xmlrpclib (Python3 uses xmlrpc.client instead) to interact with aria2:

import xmlrpclib
from pprint import pprint

s = xmlrpclib.ServerProxy("http://localhost:6800/rpc")
r = s.aria2.addUri(["http://localhost/aria2.tar.bz2"], {"dir":"/downloads"})
pprint(r)

🌈 MISC 🌈

🍓 Console Readout 🍓

While downloading files, aria2 prints a readout to the console to show the progress of the downloads. The console readout looks like this:

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

okay so this section is literally just me decoding what all these numbers and strings mean 💅

#NNNNNN — the first 6 characters of the GID as a hex string. The GID is a unique ID for each download, internal to aria2. It's particularly useful when you're interacting with aria2 using the RPC interface.
X/Y(Z%) — completed length, the total file length, and its progress. If --select-file is used, this is the sum of selected files.
SEED — share ratio when aria2 is seeding a finished torrent.
CN — the number of connections aria2 has established.
SD — the number of seeders aria2 is connected to.
DL — download speed (bytes per second).
UL — upload speed (bytes per second) and the number of uploaded bytes.
ETA — expected time to finish the download.

When more than one download is in progress, some of the information described above gets omitted, so that information for several downloads can be shown. And the overall download and upload speeds get shown at the beginning of the line. multi-tasking queen ✨

When aria2 is allocating file space or validating checksums, it additionally prints the progress of these operations:

FileAlloc — GID, already allocated length and total length in bytes.
Checksum — GID, already validated length and total length in bytes.

🌟 EXAMPLE 🌟

bestie this is the part where it all comes together, the demo reel, the highlight tape 💖 every single one of these is a real command you can paste and run fr fr.

🎀 HTTP/FTP Segmented Downloads

💅 Download a file

$ aria2c "http://host/file.zip"

NOTE: to stop a download, hit Ctrl-C. You can resume the transfer by running aria2c with the same argument in the same directory. And yes you can swap out the URIs, as long as they're all pointing to the same file. 🫶

🌈 Download a file from two different HTTP servers

$ aria2c "http://host/file.zip" "http://mirror/file.zip"

✨ Download a file from one host using multiple connections

$ aria2c -x2 -k1M "http://host/file.zip"

NOTE: the -x option sets the number of allowed connections, while -k sets the size of the chunks. two little flags doing big things 💅

🦋 Download a file from HTTP and FTP servers at the same time

$ aria2c "http://host1/file.zip" "ftp://host2/file.zip"

🍓 Download files listed in a text file concurrently

$ aria2c -ifiles.txt -j2

NOTE: -j sets the number of parallel downloads. multitasking queen 👑

🌸 Using a proxy

For HTTP:

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

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

For FTP:

$ aria2c --ftp-proxy="http://proxy:8080" "ftp://host/file"

NOTE: peep --http-proxy, --https-proxy, --ftp-proxy, --all-proxy and --no-proxy for the details. You can also specify proxy in the environment variables — go look at the ENVIRONMENT section. 💜

💖 Using a Proxy with authorization

$ aria2c --http-proxy="http://username:password@proxy:8080" "http://host/file"

$ aria2c --http-proxy="http://proxy:8080" --http-proxy-user="username" --http-proxy-passwd="password" "http://host/file"

👑 Metalink Download

💫 Download files with remote Metalink

$ aria2c --follow-metalink=mem "http://host/file.metalink"

🧚 Download using a local metalink file

$ aria2c -p --lowest-speed-limit=4000 file.metalink

NOTE: to stop a download, press Ctrl-C. You can resume the transfer by running aria2c with the same argument in the same directory. ✨

🌈 Download several local metalink files

$ aria2c -j2 file1.metalink file2.metalink

🎀 Download only selected files

$ aria2c --select-file=1-4,8 file.metalink

NOTE: the index gets printed to the console using the -S option. 🔥

🦋 Download a file using a local metalink file with user preference

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

🍓 BitTorrent Download

⭐ Download files using a remote BitTorrent file

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

💜 Download using a local torrent file

$ aria2c --max-upload-limit=40K file.torrent

NOTE: --max-upload-limit specifies the max of upload rate. 📶

NOTE: to stop a download, press Ctrl-C. You can resume the transfer later by running aria2c with the same argument in the same directory. 🫶

🌸 Download using BitTorrent Magnet URI

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

NOTE: do NOT forget to quote BitTorrent Magnet URIs which include & characters, with single (') or double (") quotes, when you're specifying URIs on the command-line. the shell will absolutely eat that ampersand otherwise and you'll be so confused 😭

💫 Download 2 torrents

$ aria2c -j2 file1.torrent file2.torrent

🎀 Download a file via torrent and HTTP/FTP server in parallel

$ aria2c -Ttest.torrent "http://host1/file" "ftp://host2/file"

✨ Only download specific files (usually called "selected download")

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

NOTE: the index gets printed to the console using the -S option. 🔍

🌈 Download a `.torrent` file, but do not download the torrent

$ aria2c --follow-torrent=false "http://host/file.torrent"

💅 Specify the output file name

To specify the output file name for BitTorrent downloads, you need to know the index of the file in the torrent (see --show-files). For example, the output looks like this:

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

To save 'dist/base-2.6.18.iso' in '/tmp/mydir/base.iso' and 'dist/driver-2.6.18.iso' in '/tmp/dir/driver.iso', use the following command:

$ aria2c --dir=/tmp --index-out=1=mydir/base.iso --index-out=2=dir/driver.iso file.torrent

🧚 Change the listening ports for incoming peer connections

$ aria2c --listen-port=7000-7001,8000 file.torrent

NOTE: since aria2 doesn't configure firewalls or routers for port forwarding, it's up to you to do so manually. it's giving DIY main character energy, no cap 🔧

🫶 Specify conditions to stop seeding after torrent downloads finish

$ aria2c --seed-time=120 --seed-ratio=1.0 file.torrent

NOTE: in the above example, the program stops seeding after 120 minutes since download completed, or once the seed ratio reaches 1.0. whichever comes first bestie ⏰

💜 Throttle upload speed

$ aria2c --max-upload-limit=100K file.torrent

🌟 Enable IPv4 DHT

$ aria2c --enable-dht --dht-listen-port=6881 file.torrent

NOTE: DHT uses UDP. Since aria2 doesn't configure firewalls or routers for port forwarding, it's up to you to do it manually. 🛠️

⭐ Enable IPv6 DHT

$ aria2c --enable-dht6 --dht-listen-port=6881 --dht-listen-addr6=YOUR_GLOBAL_UNICAST_IPV6_ADDR

NOTE: aria2 uses the same ports as IPv4 for IPv6. iykyk 🌐

🎀 Add and remove tracker URIs

Ignore all tracker announce URIs defined in file.torrent and use http://tracker1/announce and http://tracker2/announce instead:

$ aria2c --bt-exclude-tracker="*" --bt-tracker="http://tracker1/announce,http://tracker2/announce" file.torrent

🌈 More advanced HTTP features

🍓 Load cookies

$ aria2c --load-cookies=cookies.txt "http://host/file.zip"

NOTE: you can use Firefox/Mozilla/Chromium's cookie files without modification. no conversion arc, we love a plug-and-play moment 💅

🦋 Resume download started by web browsers or other programs

$ aria2c -c -s2 "http://host/partiallydownloadedfile.zip"

NOTE: this will only work when the initial download was not multi-segmented. important detail bestie, don't skip it 😭

💖 Client certificate authorization for SSL/TLS

Specify a PKCS12 file as follows:

$ aria2c --certificate=/path/to/mycert.p12

NOTE: the file specified in --certificate must be contain one PKCS12 encoded certificate and key. The password must be blank. ✨

Alternatively, if PEM files are supported, use a command like the following:

$ aria2c --certificate=/path/to/mycert.pem --private-key=/path/to/mykey.pem https://host/file

NOTE: the file specified in --private-key must be decrypted; an encrypted key may cause undefined behavior. like actually undefined, not a vibe 😭

🌸 Verify SSL/TLS servers using given CA certificates

$ aria2c --ca-certificate=/path/to/ca-certificates.crt --check-certificate https://host/file

NOTE: this option is only available when aria2 was compiled against GnuTLS or OpenSSL. WinTLS and AppleTLS will always use the system certificate store. Instead of --ca-certificate, install the certificate in that store. 🗂️

👑 RPC

💫 Encrypt RPC traffic with SSL/TLS

Specify a server PKC12 file:

$ aria2c --enable-rpc --rpc-certificate=/path/to/server.p12 --rpc-secure

NOTE: the file specified in --rpc-certificate must be contain one PKCS12 encoded certificate and key. The password must be blank. 🔐

Alternatively, when PEM files are supported (GnuTLS and OpenSSL), specify the server certificate file and private key file as follows:

$ aria2c --enable-rpc --rpc-certificate=/path/to/server.crt --rpc-private-key=/path/to/server.key --rpc-secure

✨ And more advanced features

💅 Throttle the download speed

Per-download:

$ aria2c --max-download-limit=100K file.metalink

Overall:

$ aria2c --max-overall-download-limit=100K file.metalink

🧚 Repair a damaged download

$ aria2c -V file.metalink

NOTE: repairing damaged downloads can be done efficiently when used with BitTorrent or Metalink with chunk checksums. glow-up via verification 🩹✨

⭐ Drop connections if download speed is lower than a specified limit

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

🎀 Parameterized URI support

You can specify set of parts:

$ aria2c -P "http://{host1,host2,host3}/file.iso"

You can specify numeric sequence:

$ aria2c -Z -P "http://host/image[000-100].png"

NOTE: the -Z option is required if the URIs don't point to the same file, such as in the above example. 🚨

You can specify step counter:

$ aria2c -Z -P "http://host/image[A-Z:2].png"

🌈 Verifying checksums

$ aria2c --checksum=sha-1=0192ba11326fe2298c8cb4de616f4d4140213837 http://example.org/file

💜 Parallel downloads of an arbitrary number of URIs, metalink, torrent

$ aria2c -j3 -Z "http://host/file1" file2.torrent file3.metalink

🍓 BitTorrent Encryption

Encrypt the whole payload using ARC4 (obfuscation):

$ aria2c --bt-min-crypto-level=arc4 --bt-require-crypto=true file.torrent

💖 SEE ALSO 💖

Project Web Site: https://aria2.github.io/
Metalink Homepage: http://www.metalinker.org/
The Metalink Download Description Format: RFC 5854

👑 COPYRIGHT 👑

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

In addition, as a special exception, the copyright holders give permission to link the code of portions of this program with the OpenSSL library under certain conditions as described in each individual source file, and distribute linked combinations including the two. You must obey the GNU General Public License in all respects for all of the code used other than OpenSSL. If you modify file(s) with this exception, you may extend this exception to your version of the file(s), but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version. If you delete this exception statement from all source files in the program, then also delete it here.

and that's the whole page bestie, we did it 🎉 this version is from aria2 1.37.0, dated Nov 15, 2023, and it lives under the name ARIA2C(1). go forth and download literally everything, responsibly, with the correct number of connections 💅💖✨

📦 where this page comes from

alpine 3.24: aria2-doc 1.37.0-r2 · GPL-2.0-or-later
arch rolling: aria2 1.37.0-3 · GPL-2.0-only
epel 10: aria2 1.37.0-6.el10_1 · LicenseRef-Callaway-GPLv2+-with-exceptions
fedora 43: aria2 1.37.0-7.fc43 · LicenseRef-Callaway-GPLv2+-with-exceptions
fedora 44: aria2 1.37.0-9.fc44 · LicenseRef-Callaway-GPLv2+-with-exceptions
opensuse-leap 16.0: aria2 1.37.0-bp160.2.1 · LicenseRef-SUSE-GPL-2.0-with-openssl-exception
opensuse-leap 16.0: aria2 1.37.0-bp160.2.1 · LicenseRef-SUSE-GPL-2.0-with-openssl-exception
opensuse-leap 16.0: aria2 1.37.0-bp160.2.1 · LicenseRef-SUSE-GPL-2.0-with-openssl-exception
opensuse-leap 16.0: aria2 1.37.0-bp160.2.1 · LicenseRef-SUSE-GPL-2.0-with-openssl-exception
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms

ARIA2C(1)

ARIA2C(1) — aria2c, the ultra fast download utility 💖✨

🌸 NAME

✨ SYNOPSIS

💫 DESCRIPTION

🎀 OPTIONS

💅 Basic Options

🌐 HTTP/FTP/SFTP Options

HTTP Specific Options 🌈💖

FTP/SFTP Specific Options 📁✨

🌈 BitTorrent/Metalink Options 🌈

🔥 BitTorrent Specific Options 🔥

🌟 Metalink Specific Options 🌟

💅 RPC Options 💅

⭐ Advanced Options ⭐

🎀 Notes for Options 🎀

Optional arguments ✨

Units (K and M) 💅

✨ URI, MAGNET, TORRENT_FILE, METALINK_FILE ✨

💖 Resuming Download 💖

🦋 Event Hook 🦋

🔥 EXIT STATUS 🔥

🌸 ENVIRONMENT 🌸

📁 FILES 📁

🌸 aria2.conf

🦋 dht.dat

💜 Netrc

🎀 Control File

🌈 Input File

⭐ Server Performance Profile ⭐

🛰️ RPC INTERFACE 🛰️

🌸 Terminology 🌸

💖 GID 💖

🔐 RPC authorization secret token 🔐

✨ Methods ✨

🌈 aria2.addUri([secret], uris[, options[, position]])

🦋 aria2.addTorrent([secret], torrent[, uris[, options[, position]]])

🎀 aria2.addMetalink([secret], metalink[, options[, position]])

💅 aria2.remove([secret], gid)

💅 aria2.forceRemove([secret], gid)

🛑 aria2.pause([secret], gid)

🫶 aria2.pauseAll([secret])

💥 aria2.forcePause([secret], gid)

💥 aria2.forcePauseAll([secret])

▶️ aria2.unpause([secret], gid)

🌈 aria2.unpauseAll([secret])

🔍 aria2.tellStatus([secret], gid[, keys])

🐍 JSON-RPC Example

🐍 XML-RPC Example

🦋 aria2.getUris([secret], gid) 🦋

🎀 aria2.getFiles([secret], gid) 🎀

👑 aria2.getPeers([secret], gid) 👑

🌈 aria2.getServers([secret], gid) 🌈

aria2.tellActive([secret][, keys])

aria2.tellWaiting([secret], offset, num[, keys])

aria2.tellStopped([secret], offset, num[, keys])

aria2.changePosition([secret], gid, pos, how)

JSON-RPC Example

XML-RPC Example

aria2.changeUri([secret], gid, fileIndex, delUris, addUris[, position])

JSON-RPC Example

XML-RPC Example

aria2.getOption([secret], gid)

JSON-RPC Example

XML-RPC Example

aria2.changeOption([secret], gid, options)

JSON-RPC Example

XML-RPC Example

aria2.getGlobalOption([secret])

aria2.changeGlobalOption([secret], options)

aria2.getGlobalStat([secret])

aria2.purgeDownloadResult([secret])

aria2.removeDownloadResult([secret], gid)

aria2.getVersion([secret])

aria2.getSessionInfo([secret])

aria2.shutdown([secret])

aria2.forceShutdown([secret])

aria2.saveSession([secret])

system.multicall(methods)

system.listMethods()

ARIA2C(1) — `aria2c`, the ultra fast download utility 💖✨

🌈 `aria2.addUri([secret], uris[, options[, position]])`

🦋 `aria2.addTorrent([secret], torrent[, uris[, options[, position]]])`

🎀 `aria2.addMetalink([secret], metalink[, options[, position]])`

💅 `aria2.remove([secret], gid)`

💅 `aria2.forceRemove([secret], gid)`

🛑 `aria2.pause([secret], gid)`

🫶 `aria2.pauseAll([secret])`

💥 `aria2.forcePause([secret], gid)`

💥 `aria2.forcePauseAll([secret])`

▶️ `aria2.unpause([secret], gid)`

🌈 `aria2.unpauseAll([secret])`

🔍 `aria2.tellStatus([secret], gid[, keys])`

🦋 `aria2.getUris([secret], gid)` 🦋

🎀 `aria2.getFiles([secret], gid)` 🎀

👑 `aria2.getPeers([secret], gid)` 👑

🌈 `aria2.getServers([secret], gid)` 🌈

`aria2.onDownloadStart(event)`

`aria2.onDownloadPause(event)`

`aria2.onDownloadStop(event)`

`aria2.onDownloadComplete(event)`

`aria2.onDownloadError(event)`

`aria2.onBtDownloadComplete(event)`

🌈 Download a `.torrent` file, but do not download the torrent