1ARIA2C(1) aria2 ARIA2C(1)
2
6 aria2c - The ultra fast download utility
7
9 aria2c [<OPTIONS>] [<URI>|<MAGNET>|<TORRENT_FILE>|<METALINK_FILE>] ...
10
12 aria2 is a utility for downloading files. The supported protocols are
13 HTTP(S), FTP, SFTP, BitTorrent, and Metalink. aria2 can download a file
14 from multiple sources/protocols and tries to utilize your maximum down‐
15 load bandwidth. It supports downloading a file from HTTP(S)/FTP /SFTP
16 and BitTorrent at the same time, while the data downloaded from
17 HTTP(S)/FTP/SFTP is uploaded to the BitTorrent swarm. Using Metalink
18 chunk checksums, aria2 automatically validates chunks of data while
19 downloading a file.
20
22 NOTE:
23 Most FTP related options are applicable to SFTP as well. Some op‐
24 tions are not effective against SFTP (e.g., --ftp-pasv)
25 Basic Options
27 -d, --dir=<DIR>
28 The directory to store the downloaded file.
29 -i, --input-file=<FILE>
31 Downloads the URIs listed in FILE. You can specify multiple
32 sources for a single entity by putting multiple URIs on a single
33 line separated by the TAB character. Additionally, options can
34 be specified after each URI line. Option lines must start with
35 one or more white space characters (SPACE or TAB) and must only
36 contain one option per line. Input files can use gzip compres‐
37 sion. When FILE is specified as -, aria2 will read the input
38 from stdin. See the Input File subsection for details. See
39 also the --deferred-input option. See also the --save-session
40 option.
41 -l, --log=<LOG>
43 The file name of the log file. If - is specified, log is written
44 to stdout. If empty string("") is specified, or this option is
45 omitted, no log is written to disk at all.
46 -j, --max-concurrent-downloads=<N>
48 Set the maximum number of parallel downloads for every queue
49 item. See also the --split option. Default: 5
50 NOTE:
52 --max-concurrent-downloads limits the number of items which
53 are downloaded concurrently. --split and --min-split-size
54 affect the number of connections inside each item. Imagine
55 that you have an input file (see --input-file option) like
56 this:
57 http://example.com/foo
59 http://example.com/bar
60 Here is 2 download items. aria2 can download these items
62 concurrently if the value more than or equal 2 is given to
63 --max-concurrent-downloads. In each download item, you can
64 configure the number of connections using --split and/or
65 --min-split-size, etc.
66 -V, --check-integrity [true|false]
68 Check file integrity by validating piece hashes or a hash of en‐
69 tire file. This option has effect only in BitTorrent, Metalink
70 downloads with checksums or HTTP(S)/FTP downloads with
71 --checksum option. If piece hashes are provided, this option
72 can detect damaged portions of a file and re-download them. If
73 a hash of entire file is provided, hash check is only done when
74 file has been already download. This is determined by file
75 length. If hash check fails, file is re-downloaded from scratch.
76 If both piece hashes and a hash of entire file are provided,
77 only piece hashes are used. Default: false
78 -c, --continue [true|false]
80 Continue downloading a partially downloaded file. Use this op‐
81 tion to resume a download started by a web browser or another
82 program which downloads files sequentially from the beginning.
83 Currently this option is only applicable to HTTP(S)/FTP down‐
84 loads.
85 -h, --help[=<TAG>|<KEYWORD>]
87 The help messages are classified with tags. A tag starts with #.
88 For example, type --help=#http to get the usage for the options
89 tagged with #http. If non-tag word is given, print the usage for
90 the options whose name includes that word. Available Values:
91 #basic, #advanced, #http, #https, #ftp, #metalink, #bittorrent,
92 #cookie, #hook, #file, #rpc, #checksum, #experimental, #depre‐
93 cated, #help, #all Default: #basic
94 HTTP/FTP/SFTP Options
96 --all-proxy=<PROXY>
97 Use a proxy server for all protocols. To override a previously
98 defined proxy, use "". You also can override this setting and
99 specify a proxy server for a particular protocol using
100 --http-proxy, --https-proxy and --ftp-proxy options. This af‐
101 fects all downloads. The format of PROXY is
102 [http://][USER:PASSWORD@]HOST[:PORT]. See also ENVIRONMENT sec‐
103 tion.
104 NOTE:
106 If user and password are embedded in proxy URI and they are
107 also specified by --{http,https,ftp,all}-proxy-{user,passwd}
108 options, those specified later override prior options. For
109 example, if you specified http-proxy-user=myname,
110 http-proxy-passwd=mypass in aria2.conf and you specified
111 --http-proxy="http://proxy" on the command-line, then you'd
112 get HTTP proxy http://proxy with user myname and password my‐
113 pass.
114 Another example: if you specified on the command-line
116 --http-proxy="http://user:pass@proxy" --http-proxy-user="my‐
117 name" --http-proxy-passwd="mypass", then you'd get HTTP proxy
118 http://proxy with user myname and password mypass.
119 One more example: if you specified in command-line
121 --http-proxy-user="myname" --http-proxy-passwd="mypass"
122 --http-proxy="http://user:pass@proxy", then you'd get HTTP
123 proxy http://proxy with user user and password pass.
124 --all-proxy-passwd=<PASSWD>
126 Set password for --all-proxy option.
127 --all-proxy-user=<USER>
129 Set user for --all-proxy option.
130 --checksum=<TYPE>=<DIGEST>
132 Set checksum. TYPE is hash type. The supported hash type is
133 listed in Hash Algorithms in aria2c -v. DIGEST is hex digest.
134 For example, setting sha-1 digest looks like this:
135 sha-1=0192ba11326fe2298c8cb4de616f4d4140213838 This option ap‐
136 plies only to HTTP(S)/FTP downloads.
137 --connect-timeout=<SEC>
139 Set the connect timeout in seconds to establish connection to
140 HTTP/FTP/proxy server. After the connection is established, this
141 option makes no effect and --timeout option is used instead.
142 Default: 60
143 --dry-run [true|false]
145 If true is given, aria2 just checks whether the remote file is
146 available and doesn't download data. This option has effect on
147 HTTP/FTP download. BitTorrent downloads are canceled if true is
148 specified. Default: false
149 --lowest-speed-limit=<SPEED>
151 Close connection if download speed is lower than or equal to
152 this value(bytes per sec). 0 means aria2 does not have a lowest
153 speed limit. You can append K or M (1K = 1024, 1M = 1024K).
154 This option does not affect BitTorrent downloads. Default: 0
155 -x, --max-connection-per-server=<NUM>
157 The maximum number of connections to one server for each down‐
158 load. Default: 1
159 --max-file-not-found=<NUM>
161 If aria2 receives "file not found" status from the remote
162 HTTP/FTP servers NUM times without getting a single byte, then
163 force the download to fail. Specify 0 to disable this option.
164 This options is effective only when using HTTP/FTP servers. The
165 number of retry attempt is counted toward --max-tries, so it
166 should be configured too.
167 Default: 0
169 -m, --max-tries=<N>
171 Set number of tries. 0 means unlimited. See also --retry-wait.
172 Default: 5
173 -k, --min-split-size=<SIZE>
175 aria2 does not split less than 2*SIZE byte range. For example,
176 let's consider downloading 20MiB file. If SIZE is 10M, aria2 can
177 split file into 2 range [0-10MiB) and [10MiB-20MiB) and download
178 it using 2 sources(if --split >= 2, of course). If SIZE is 15M,
179 since 2*15M > 20MiB, aria2 does not split file and download it
180 using 1 source. You can append K or M (1K = 1024, 1M = 1024K).
181 Possible Values: 1M -1024M Default: 20M
182 --netrc-path=<FILE>
184 Specify the path to the netrc file. Default: $(HOME)/.netrc
185 NOTE:
187 Permission of the .netrc file must be 600. Otherwise, the
188 file will be ignored.
189 -n, --no-netrc [true|false]
191 Disables netrc support. netrc support is enabled by default.
192 NOTE:
194 netrc file is only read at the startup if --no-netrc is
195 false. So if --no-netrc is true at the startup, no netrc is
196 available throughout the session. You cannot get netrc en‐
197 abled even if you send --no-netrc=false using
198 aria2.changeGlobalOption().
199 --no-proxy=<DOMAINS>
201 Specify a comma separated list of host names, domains and net‐
202 work addresses with or without a subnet mask where no proxy
203 should be used.
204 NOTE:
206 For network addresses with a subnet mask, both IPv4 and IPv6
207 addresses work. The current implementation does not resolve
208 the host name in an URI to compare network addresses speci‐
209 fied in --no-proxy. So it is only effective if URI has nu‐
210 meric IP addresses.
211 -o, --out=<FILE>
213 The file name of the downloaded file. It is always relative to
214 the directory given in --dir option. When the
215 --force-sequential option is used, this option is ignored.
216 NOTE:
218 You cannot specify a file name for Metalink or BitTorrent
219 downloads. The file name specified here is only used when
220 the URIs fed to aria2 are given on the command line directly,
221 but not when using --input-file, --force-sequential option.
222 Example:
224 $ aria2c -o myfile.zip "http://mirror1/file.zip" "http://mirror2/file.zip"
226 --proxy-method=<METHOD>
228 Set the method to use in proxy request. METHOD is either get or
229 tunnel. HTTPS downloads always use tunnel regardless of this op‐
230 tion. Default: get
231 -R, --remote-time [true|false]
233 Retrieve timestamp of the remote file from the remote HTTP/FTP
234 server and if it is available, apply it to the local file. De‐
235 fault: false
236 --reuse-uri [true|false]
238 Reuse already used URIs if no unused URIs are left. Default:
239 true
240 --retry-wait=<SEC>
242 Set the seconds to wait between retries. When SEC > 0, aria2
243 will retry downloads when the HTTP server returns a 503 re‐
244 sponse. Default: 0
245 --server-stat-of=<FILE>
247 Specify the file name to which performance profile of the
248 servers is saved. You can load saved data using --server-stat-if
249 option. See Server Performance Profile subsection below for file
250 format.
251 --server-stat-if=<FILE>
253 Specify the file name to load performance profile of the
254 servers. The loaded data will be used in some URI selector such
255 as feedback. See also --uri-selector option. See Server Perfor‐
256 mance Profile subsection below for file format.
257 --server-stat-timeout=<SEC>
259 Specifies timeout in seconds to invalidate performance profile
260 of the servers since the last contact to them. Default: 86400
261 (24hours)
262 -s, --split=<N>
264 Download a file using N connections. If more than N URIs are
265 given, first N URIs are used and remaining URIs are used for
266 backup. If less than N URIs are given, those URIs are used more
267 than once so that N connections total are made simultaneously.
268 The number of connections to the same host is restricted by the
269 --max-connection-per-server option. See also the
270 --min-split-size option. Default: 5
271 NOTE:
273 Some Metalinks regulate the number of servers to connect.
274 aria2 strictly respects them. This means that if Metalink
275 defines the maxconnections attribute lower than N, then aria2
276 uses the value of this lower value instead of N.
277 --stream-piece-selector=<SELECTOR>
279 Specify piece selection algorithm used in HTTP/FTP download.
280 Piece means fixed length segment which is downloaded in parallel
281 in segmented download. If default is given, aria2 selects piece
282 so that it reduces the number of establishing connection. This
283 is reasonable default behavior because establishing connection
284 is an expensive operation. If inorder is given, aria2 selects
285 piece which has minimum index. Index=0 means first of the file.
286 This will be useful to view movie while downloading it.
287 --enable-http-pipelining option may be useful to reduce re-con‐
288 nection overhead. Please note that aria2 honors
289 --min-split-size option, so it will be necessary to specify a
290 reasonable value to --min-split-size option. If random is
291 given, aria2 selects piece randomly. Like inorder,
292 --min-split-size option is honored. If geom is given, at the
293 beginning aria2 selects piece which has minimum index like in‐
294 order, but it exponentially increasingly keeps space from previ‐
295 ously selected piece. This will reduce the number of establish‐
296 ing connection and at the same time it will download the begin‐
297 ning part of the file first. This will be useful to view movie
298 while downloading it. Default: default
299 -t, --timeout=<SEC>
301 Set timeout in seconds. Default: 60
302 --uri-selector=<SELECTOR>
304 Specify URI selection algorithm. The possible values are in‐
305 order, feedback and adaptive. If inorder is given, URI is tried
306 in the order appeared in the URI list. If feedback is given,
307 aria2 uses download speed observed in the previous downloads and
308 choose fastest server in the URI list. This also effectively
309 skips dead mirrors. The observed download speed is a part of
310 performance profile of servers mentioned in --server-stat-of and
311 --server-stat-if options. If adaptive is given, selects one of
312 the best mirrors for the first and reserved connections. For
313 supplementary ones, it returns mirrors which has not been tested
314 yet, and if each of them has already been tested, returns mir‐
315 rors which has to be tested again. Otherwise, it doesn't select
316 anymore mirrors. Like feedback, it uses a performance profile of
317 servers. Default: feedback
318 HTTP Specific Options
320 --ca-certificate=<FILE>
321 Use the certificate authorities in FILE to verify the peers.
322 The certificate file must be in PEM format and can contain mul‐
323 tiple CA certificates. Use --check-certificate option to enable
324 verification.
325 NOTE:
327 If you build with OpenSSL or the recent version of GnuTLS
328 which has gnutls_certificate_set_x509_system_trust() function
329 and the library is properly configured to locate the sys‐
330 tem-wide CA certificates store, aria2 will automatically load
331 those certificates at the startup.
332 NOTE:
334 WinTLS and AppleTLS do not support this option. Instead you
335 will have to import the certificate into the OS trust store.
336 --certificate=<FILE>
338 Use the client certificate in FILE. The certificate must be ei‐
339 ther in PKCS12 (.p12, .pfx) or in PEM format.
340 PKCS12 files must contain the certificate, a key and optionally
342 a chain of additional certificates. Only PKCS12 files with a
343 blank import password can be opened!
344 When using PEM, you have to specify the private key via
346 --private-key as well.
347 NOTE:
349 WinTLS does not support PEM files at the moment. Users have
350 to use PKCS12 files.
351 NOTE:
353 AppleTLS users should use the KeyChain Access utility to im‐
354 port the client certificate and get the SHA-1 fingerprint
355 from the Information dialog corresponding to that certifi‐
356 cate. To start aria2c use --certificate=<SHA-1>. Alterna‐
357 tively PKCS12 files are also supported. PEM files, however,
358 are not supported.
359 --check-certificate [true|false]
361 Verify the peer using certificates specified in --ca-certificate
362 option. Default: true
363 --http-accept-gzip [true|false]
365 Send Accept: deflate, gzip request header and inflate response
366 if remote server responds with Content-Encoding: gzip or Con‐
367 tent-Encoding: deflate. Default: false
368 NOTE:
370 Some server responds with Content-Encoding: gzip for files
371 which itself is gzipped file. aria2 inflates them anyway be‐
372 cause of the response header.
373 --http-auth-challenge [true|false]
375 Send HTTP authorization header only when it is requested by the
376 server. If false is set, then authorization header is always
377 sent to the server. There is an exception: if user name and
378 password are embedded in URI, authorization header is always
379 sent to the server regardless of this option. Default: false
380 --http-no-cache [true|false]
382 Send Cache-Control: no-cache and Pragma: no-cache header to
383 avoid cached content. If false is given, these headers are not
384 sent and you can add Cache-Control header with a directive you
385 like using --header option. Default: false
386 --http-user=<USER>
388 Set HTTP user. This affects all URIs.
389 --http-passwd=<PASSWD>
391 Set HTTP password. This affects all URIs.
392 --http-proxy=<PROXY>
394 Use a proxy server for HTTP. To override a previously defined
395 proxy, use "". See also the --all-proxy option. This affects
396 all http downloads. The format of PROXY is [http://][USER:PASS‐
397 WORD@]HOST[:PORT]
398 --http-proxy-passwd=<PASSWD>
400 Set password for --http-proxy.
401 --http-proxy-user=<USER>
403 Set user for --http-proxy.
404 --https-proxy=<PROXY>
406 Use a proxy server for HTTPS. To override a previously defined
407 proxy, use "". See also the --all-proxy option. This affects
408 all https download. The format of PROXY is [http://][USER:PASS‐
409 WORD@]HOST[:PORT]
410 --https-proxy-passwd=<PASSWD>
412 Set password for --https-proxy.
413 --https-proxy-user=<USER>
415 Set user for --https-proxy.
416 --private-key=<FILE>
418 Use the private key in FILE. The private key must be decrypted
419 and in PEM format. The behavior when encrypted one is given is
420 undefined. See also --certificate option.
421 --referer=<REFERER>
423 Set an http referrer (Referer). This affects all http/https
424 downloads. If * is given, the download URI is also used as the
425 referrer. This may be useful when used together with the
426 --parameterized-uri option.
427 --enable-http-keep-alive [true|false]
429 Enable HTTP/1.1 persistent connection. Default: true
430 --enable-http-pipelining [true|false]
432 Enable HTTP/1.1 pipelining. Default: false
433 NOTE:
435 In performance perspective, there is usually no advantage to
436 enable this option.
437 --header=<HEADER>
439 Append HEADER to HTTP request header. You can use this option
440 repeatedly to specify more than one header:
441 $ aria2c --header="X-A: b78" --header="X-B: 9J1" "http://host/file"
443 --load-cookies=<FILE>
445 Load Cookies from FILE using the Firefox3 format (SQLite3),
446 Chromium/Google Chrome (SQLite3) and the Mozilla/Fire‐
447 fox(1.x/2.x)/Netscape format.
448 NOTE:
450 If aria2 is built without libsqlite3, then it doesn't support
451 Firefox3 and Chromium/Google Chrome cookie format.
452 --save-cookies=<FILE>
454 Save Cookies to FILE in Mozilla/Firefox(1.x/2.x)/ Netscape for‐
455 mat. If FILE already exists, it is overwritten. Session Cookies
456 are also saved and their expiry values are treated as 0. Possi‐
457 ble Values: /path/to/file
458 --use-head [true|false]
460 Use HEAD method for the first request to the HTTP server. De‐
461 fault: false
462 -U, --user-agent=<USER_AGENT>
464 Set user agent for HTTP(S) downloads. Default: aria2/$VERSION,
465 $VERSION is replaced by package version.
466 FTP/SFTP Specific Options
468 --ftp-user=<USER>
469 Set FTP user. This affects all URIs. Default: anonymous
470 --ftp-passwd=<PASSWD>
472 Set FTP password. This affects all URIs. If user name is embed‐
473 ded but password is missing in URI, aria2 tries to resolve pass‐
474 word using .netrc. If password is found in .netrc, then use it
475 as password. If not, use the password specified in this option.
476 Default: ARIA2USER@
477 -p, --ftp-pasv [true|false]
479 Use the passive mode in FTP. If false is given, the active mode
480 will be used. Default: true
481 NOTE:
483 This option is ignored for SFTP transfer.
484 --ftp-proxy=<PROXY>
486 Use a proxy server for FTP. To override a previously defined
487 proxy, use "". See also the --all-proxy option. This affects
488 all ftp downloads. The format of PROXY is [http://][USER:PASS‐
489 WORD@]HOST[:PORT]
490 --ftp-proxy-passwd=<PASSWD>
492 Set password for --ftp-proxy option.
493 --ftp-proxy-user=<USER>
495 Set user for --ftp-proxy option.
496 --ftp-type=<TYPE>
498 Set FTP transfer type. TYPE is either binary or ascii. Default:
499 binary
500 NOTE:
502 This option is ignored for SFTP transfer.
503 --ftp-reuse-connection [true|false]
505 Reuse connection in FTP. Default: true
506 --ssh-host-key-md=<TYPE>=<DIGEST>
508 Set checksum for SSH host public key. TYPE is hash type. The
509 supported hash type is sha-1 or md5. DIGEST is hex digest. For
510 example: sha-1=b030503d4de4539dc7885e6f0f5e256704edf4c3. This
511 option can be used to validate server's public key when SFTP is
512 used. If this option is not set, which is default, no validation
513 takes place.
514 BitTorrent/Metalink Options
516 --select-file=<INDEX>...
517 Set file to download by specifying its index. You can find the
518 file index using the --show-files option. Multiple indexes can
519 be specified by using ,, for example: 3,6. You can also use -
520 to specify a range: 1-5. , and - can be used together: 1-5,8,9.
521 When used with the -M option, index may vary depending on the
522 query (see --metalink-* options).
523 NOTE:
525 In multi file torrent, the adjacent files specified by this
526 option may also be downloaded. This is by design, not a bug.
527 A single piece may include several files or part of files,
528 and aria2 writes the piece to the appropriate files.
529 -S, --show-files [true|false]
531 Print file listing of ".torrent", ".meta4" and ".metalink" file
532 and exit. In case of ".torrent" file, additional information
533 (infohash, piece length, etc) is also printed.
534 BitTorrent Specific Options
536 --bt-detach-seed-only [true|false]
537 Exclude seed only downloads when counting concurrent active
538 downloads (See -j option). This means that if -j3 is given and
539 this option is turned on and 3 downloads are active and one of
540 those enters seed mode, then it is excluded from active download
541 count (thus it becomes 2), and the next download waiting in
542 queue gets started. But be aware that seeding item is still rec‐
543 ognized as active download in RPC method. Default: false
544 --bt-enable-hook-after-hash-check [true|false]
546 Allow hook command invocation after hash check (see -V option)
547 in BitTorrent download. By default, when hash check succeeds,
548 the command given by --on-bt-download-complete is executed. To
549 disable this action, give false to this option. Default: true
550 --bt-enable-lpd [true|false]
552 Enable Local Peer Discovery. If a private flag is set in a tor‐
553 rent, aria2 doesn't use this feature for that download even if
554 true is given. Default: false
555 --bt-exclude-tracker=<URI>[,...]
557 Comma separated list of BitTorrent tracker's announce URI to re‐
558 move. You can use special value * which matches all URIs, thus
559 removes all announce URIs. When specifying * in shell com‐
560 mand-line, don't forget to escape or quote it. See also
561 --bt-tracker option.
562 --bt-external-ip=<IPADDRESS>
564 Specify the external IP address to use in BitTorrent download
565 and DHT. It may be sent to BitTorrent tracker. For DHT, this
566 option should be set to report that local node is downloading a
567 particular torrent. This is critical to use DHT in a private
568 network. Although this function is named external, it can accept
569 any kind of IP addresses.
570 --bt-force-encryption [true|false]
572 Requires BitTorrent message payload encryption with arc4. This
573 is a shorthand of --bt-require-crypto
574 --bt-min-crypto-level=arc4. This option does not change the op‐
575 tion value of those options. If true is given, deny legacy Bit‐
576 Torrent handshake and only use Obfuscation handshake and always
577 encrypt message payload. Default: false
578 --bt-hash-check-seed [true|false]
580 If true is given, after hash check using --check-integrity op‐
581 tion and file is complete, continue to seed file. If you want to
582 check file and download it only when it is damaged or incom‐
583 plete, set this option to false. This option has effect only on
584 BitTorrent download. Default: true
585 --bt-load-saved-metadata [true|false]
587 Before getting torrent metadata from DHT when downloading with
588 magnet link, first try to read file saved by --bt-save-metadata
589 option. If it is successful, then skip downloading metadata
590 from DHT. Default: false
591 --bt-lpd-interface=<INTERFACE>
593 Use given interface for Local Peer Discovery. If this option is
594 not specified, the default interface is chosen. You can specify
595 interface name and IP address. Possible Values: interface, IP
596 address
597 --bt-max-open-files=<NUM>
599 Specify maximum number of files to open in multi-file BitTor‐
600 rent/Metalink download globally. Default: 100
601 --bt-max-peers=<NUM>
603 Specify the maximum number of peers per torrent. 0 means unlim‐
604 ited. See also --bt-request-peer-speed-limit option. Default:
605 55
606 --bt-metadata-only [true|false]
608 Download meta data only. The file(s) described in meta data will
609 not be downloaded. This option has effect only when BitTorrent
610 Magnet URI is used. See also --bt-save-metadata option. De‐
611 fault: false
612 --bt-min-crypto-level=plain|arc4
614 Set minimum level of encryption method. If several encryption
615 methods are provided by a peer, aria2 chooses the lowest one
616 which satisfies the given level. Default: plain
617 --bt-prioritize-piece=head[=<SIZE>],tail[=<SIZE>]
619 Try to download first and last pieces of each file first. This
620 is useful for previewing files. The argument can contain 2 key‐
621 words: head and tail. To include both keywords, they must be
622 separated by comma. These keywords can take one parameter, SIZE.
623 For example, if head=<SIZE> is specified, pieces in the range of
624 first SIZE bytes of each file get higher priority. tail=<SIZE>
625 means the range of last SIZE bytes of each file. SIZE can in‐
626 clude K or M (1K = 1024, 1M = 1024K). If SIZE is omitted,
627 SIZE=1M is used.
628 --bt-remove-unselected-file [true|false]
630 Removes the unselected files when download is completed in Bit‐
631 Torrent. To select files, use --select-file option. If it is not
632 used, all files are assumed to be selected. Please use this op‐
633 tion with care because it will actually remove files from your
634 disk. Default: false
635 --bt-require-crypto [true|false]
637 If true is given, aria2 doesn't accept and establish connection
638 with legacy BitTorrent handshake(\19BitTorrent protocol). Thus
639 aria2 always uses Obfuscation handshake. Default: false
640 --bt-request-peer-speed-limit=<SPEED>
642 If the whole download speed of every torrent is lower than
643 SPEED, aria2 temporarily increases the number of peers to try
644 for more download speed. Configuring this option with your pre‐
645 ferred download speed can increase your download speed in some
646 cases. You can append K or M (1K = 1024, 1M = 1024K). Default:
647 50K
648 --bt-save-metadata [true|false]
650 Save meta data as ".torrent" file. This option has effect only
651 when BitTorrent Magnet URI is used. The file name is hex en‐
652 coded info hash with suffix ".torrent". The directory to be
653 saved is the same directory where download file is saved. If the
654 same file already exists, meta data is not saved. See also
655 --bt-metadata-only option. Default: false
656 --bt-seed-unverified [true|false]
658 Seed previously downloaded files without verifying piece hashes.
659 Default: false
660 --bt-stop-timeout=<SEC>
662 Stop BitTorrent download if download speed is 0 in consecutive
663 SEC seconds. If 0 is given, this feature is disabled. Default:
664 0
665 --bt-tracker=<URI>[,...]
667 Comma separated list of additional BitTorrent tracker's announce
668 URI. These URIs are not affected by --bt-exclude-tracker option
669 because they are added after URIs in --bt-exclude-tracker option
670 are removed.
671 --bt-tracker-connect-timeout=<SEC>
673 Set the connect timeout in seconds to establish connection to
674 tracker. After the connection is established, this option makes
675 no effect and --bt-tracker-timeout option is used instead. De‐
676 fault: 60
677 --bt-tracker-interval=<SEC>
679 Set the interval in seconds between tracker requests. This com‐
680 pletely overrides interval value and aria2 just uses this value
681 and ignores the min interval and interval value in the response
682 of tracker. If 0 is set, aria2 determines interval based on the
683 response of tracker and the download progress. Default: 0
684 --bt-tracker-timeout=<SEC>
686 Set timeout in seconds. Default: 60
687 --dht-entry-point=<HOST>:<PORT>
689 Set host and port as an entry point to IPv4 DHT network.
690 --dht-entry-point6=<HOST>:<PORT>
692 Set host and port as an entry point to IPv6 DHT network.
693 --dht-file-path=<PATH>
695 Change the IPv4 DHT routing table file to PATH. Default:
696 $HOME/.aria2/dht.dat if present, otherwise
697 $XDG_CACHE_HOME/aria2/dht.dat.
698 --dht-file-path6=<PATH>
700 Change the IPv6 DHT routing table file to PATH. Default:
701 $HOME/.aria2/dht6.dat if present, otherwise
702 $XDG_CACHE_HOME/aria2/dht6.dat.
703 --dht-listen-addr6=<ADDR>
705 Specify address to bind socket for IPv6 DHT. It should be a
706 global unicast IPv6 address of the host.
707 --dht-listen-port=<PORT>...
709 Set UDP listening port used by DHT(IPv4, IPv6) and UDP tracker.
710 Multiple ports can be specified by using ,, for example:
711 6881,6885. You can also use - to specify a range: 6881-6999. ,
712 and - can be used together. Default: 6881-6999
713 NOTE:
715 Make sure that the specified ports are open for incoming UDP
716 traffic.
717 --dht-message-timeout=<SEC>
719 Set timeout in seconds. Default: 10
720 --enable-dht [true|false]
722 Enable IPv4 DHT functionality. It also enables UDP tracker sup‐
723 port. If a private flag is set in a torrent, aria2 doesn't use
724 DHT for that download even if true is given. Default: true
725 --enable-dht6 [true|false]
727 Enable IPv6 DHT functionality. If a private flag is set in a
728 torrent, aria2 doesn't use DHT for that download even if true is
729 given. Use --dht-listen-port option to specify port number to
730 listen on. See also --dht-listen-addr6 option.
731 --enable-peer-exchange [true|false]
733 Enable Peer Exchange extension. If a private flag is set in a
734 torrent, this feature is disabled for that download even if true
735 is given. Default: true
736 --follow-torrent=true|false|mem
738 If true or mem is specified, when a file whose suffix is .tor‐
739 rent or content type is application/x-bittorrent is downloaded,
740 aria2 parses it as a torrent file and downloads files mentioned
741 in it. If mem is specified, a torrent file is not written to
742 the disk, but is just kept in memory. If false is specified,
743 the .torrent file is downloaded to the disk, but is not parsed
744 as a torrent and its contents are not downloaded. Default: true
745 -O, --index-out=<INDEX>=<PATH>
747 Set file path for file with index=INDEX. You can find the file
748 index using the --show-files option. PATH is a relative path to
749 the path specified in --dir option. You can use this option mul‐
750 tiple times. Using this option, you can specify the output file
751 names of BitTorrent downloads.
752 --listen-port=<PORT>...
754 Set TCP port number for BitTorrent downloads. Multiple ports
755 can be specified by using ,, for example: 6881,6885. You can
756 also use - to specify a range: 6881-6999. , and - can be used
757 together: 6881-6889,6999. Default: 6881-6999
758 NOTE:
760 Make sure that the specified ports are open for incoming TCP
761 traffic.
762 --max-overall-upload-limit=<SPEED>
764 Set max overall upload speed in bytes/sec. 0 means unre‐
765 stricted. You can append K or M (1K = 1024, 1M = 1024K). To
766 limit the upload speed per torrent, use --max-upload-limit op‐
767 tion. Default: 0
768 -u, --max-upload-limit=<SPEED>
770 Set max upload speed per each torrent in bytes/sec. 0 means un‐
771 restricted. You can append K or M (1K = 1024, 1M = 1024K). To
772 limit the overall upload speed, use --max-overall-upload-limit
773 option. Default: 0
774 --peer-id-prefix=<PEER_ID_PREFIX>
776 Specify the prefix of peer ID. The peer ID in BitTorrent is 20
777 byte length. If more than 20 bytes are specified, only first 20
778 bytes are used. If less than 20 bytes are specified, random byte
779 data are added to make its length 20 bytes.
780 Default: A2-$MAJOR-$MINOR-$PATCH-, $MAJOR, $MINOR and $PATCH are
782 replaced by major, minor and patch version number respectively.
783 For instance, aria2 version 1.18.8 has prefix ID A2-1-18-8-.
784 --peer-agent=<PEER_AGENT>
786 Specify the string used during the bitorrent extended handshake
787 for the peer's client version.
788 Default: aria2/$MAJOR.$MINOR.$PATCH, $MAJOR, $MINOR and $PATCH
790 are replaced by major, minor and patch version number respec‐
791 tively. For instance, aria2 version 1.18.8 has peer agent
792 aria2/1.18.8.
793 --seed-ratio=<RATIO>
795 Specify share ratio. Seed completed torrents until share ratio
796 reaches RATIO. You are strongly encouraged to specify equals or
797 more than 1.0 here. Specify 0.0 if you intend to do seeding re‐
798 gardless of share ratio. If --seed-time option is specified
799 along with this option, seeding ends when at least one of the
800 conditions is satisfied. Default: 1.0
801 --seed-time=<MINUTES>
803 Specify seeding time in (fractional) minutes. Also see the
804 --seed-ratio option.
805 NOTE:
807 Specifying --seed-time=0 disables seeding after download com‐
808 pleted.
809 -T, --torrent-file=<TORRENT_FILE>
811 The path to the ".torrent" file. You are not required to use
812 this option because you can specify ".torrent" files without
813 --torrent-file.
814 Metalink Specific Options
816 --follow-metalink=true|false|mem
817 If true or mem is specified, when a file whose suffix is .meta4
818 or .metalink or content type of application/metalink4+xml or ap‐
819 plication/metalink+xml is downloaded, aria2 parses it as a met‐
820 alink file and downloads files mentioned in it. If mem is spec‐
821 ified, a metalink file is not written to the disk, but is just
822 kept in memory. If false is specified, the .metalink file is
823 downloaded to the disk, but is not parsed as a metalink file and
824 its contents are not downloaded. Default: true
825 --metalink-base-uri=<URI>
827 Specify base URI to resolve relative URI in metalink:url and
828 metalink:metaurl element in a metalink file stored in local
829 disk. If URI points to a directory, URI must end with /.
830 -M, --metalink-file=<METALINK_FILE>
832 The file path to ".meta4" and ".metalink" file. Reads input from
833 stdin when - is specified. You are not required to use this op‐
834 tion because you can specify ".metalink" files without
835 --metalink-file.
836 --metalink-language=<LANGUAGE>
838 The language of the file to download.
839 --metalink-location=<LOCATION>[,...]
841 The location of the preferred server. A comma-delimited list of
842 locations is acceptable, for example, jp,us.
843 --metalink-os=<OS>
845 The operating system of the file to download.
846 --metalink-version=<VERSION>
848 The version of the file to download.
849 --metalink-preferred-protocol=<PROTO>
851 Specify preferred protocol. The possible values are http,
852 https, ftp and none. Specify none to disable this feature. De‐
853 fault: none
854 --metalink-enable-unique-protocol [true|false]
856 If true is given and several protocols are available for a mir‐
857 ror in a metalink file, aria2 uses one of them. Use
858 --metalink-preferred-protocol option to specify the preference
859 of protocol. Default: true
860 RPC Options
862 --enable-rpc [true|false]
863 Enable JSON-RPC/XML-RPC server. It is strongly recommended to
864 set secret authorization token using --rpc-secret option. See
865 also --rpc-listen-port option. Default: false
866 --pause [true|false]
868 Pause download after added. This option is effective only when
869 --enable-rpc=true is given. Default: false
870 --pause-metadata [true|false]
872 Pause downloads created as a result of metadata download. There
873 are 3 types of metadata downloads in aria2: (1) downloading
874 .torrent file. (2) downloading torrent metadata using magnet
875 link. (3) downloading metalink file. These metadata downloads
876 will generate downloads using their metadata. This option pauses
877 these subsequent downloads. This option is effective only when
878 --enable-rpc=true is given. Default: false
879 --rpc-allow-origin-all [true|false]
881 Add Access-Control-Allow-Origin header field with value * to the
882 RPC response. Default: false
883 --rpc-certificate=<FILE>
885 Use the certificate in FILE for RPC server. The certificate must
886 be either in PKCS12 (.p12, .pfx) or in PEM format.
887 PKCS12 files must contain the certificate, a key and optionally
889 a chain of additional certificates. Only PKCS12 files with a
890 blank import password can be opened!
891 When using PEM, you have to specify the private key via
893 --rpc-private-key as well. Use --rpc-secure option to enable en‐
894 cryption.
895 NOTE:
897 WinTLS does not support PEM files at the moment. Users have
898 to use PKCS12 files.
899 NOTE:
901 AppleTLS users should use the KeyChain Access utility to
902 first generate a self-signed SSL-Server certificate, e.g. us‐
903 ing the wizard, and get the SHA-1 fingerprint from the Infor‐
904 mation dialog corresponding to that new certificate. To
905 start aria2c with --rpc-secure use --rpc-certificate=<SHA-1>.
906 Alternatively PKCS12 files are also supported. PEM files,
907 however, are not supported.
908 --rpc-listen-all [true|false]
910 Listen incoming JSON-RPC/XML-RPC requests on all network inter‐
911 faces. If false is given, listen only on local loopback inter‐
912 face. Default: false
913 --rpc-listen-port=<PORT>
915 Specify a port number for JSON-RPC/XML-RPC server to listen to.
916 Possible Values: 1024 -65535 Default: 6800
917 --rpc-max-request-size=<SIZE>
919 Set max size of JSON-RPC/XML-RPC request. If aria2 detects the
920 request is more than SIZE bytes, it drops connection. Default:
921 2M
922 --rpc-passwd=<PASSWD>
924 Set JSON-RPC/XML-RPC password.
925 WARNING:
927 --rpc-passwd option will be deprecated in the future release.
928 Migrate to --rpc-secret option as soon as possible.
929 --rpc-private-key=<FILE>
931 Use the private key in FILE for RPC server. The private key
932 must be decrypted and in PEM format. Use --rpc-secure option to
933 enable encryption. See also --rpc-certificate option.
934 --rpc-save-upload-metadata [true|false]
936 Save the uploaded torrent or metalink meta data in the directory
937 specified by --dir option. The file name consists of SHA-1 hash
938 hex string of meta data plus extension. For torrent, the exten‐
939 sion is '.torrent'. For metalink, it is '.meta4'. If false is
940 given to this option, the downloads added by aria2.addTorrent()
941 or aria2.addMetalink() will not be saved by --save-session op‐
942 tion. Default: true
943 --rpc-secret=<TOKEN>
945 Set RPC secret authorization token. Read RPC authorization se‐
946 cret token to know how this option value is used.
947 --rpc-secure [true|false]
949 RPC transport will be encrypted by SSL/TLS. The RPC clients
950 must use https scheme to access the server. For WebSocket
951 client, use wss scheme. Use --rpc-certificate and
952 --rpc-private-key options to specify the server certificate and
953 private key.
954 --rpc-user=<USER>
956 Set JSON-RPC/XML-RPC user.
957 WARNING:
959 --rpc-user option will be deprecated in the future release.
960 Migrate to --rpc-secret option as soon as possible.
961 Advanced Options
963 --allow-overwrite [true|false]
964 Restart download from scratch if the corresponding control file
965 doesn't exist. See also --auto-file-renaming option. Default:
966 false
967 --allow-piece-length-change [true|false]
969 If false is given, aria2 aborts download when a piece length is
970 different from one in a control file. If true is given, you can
971 proceed but some download progress will be lost. Default: false
972 --always-resume [true|false]
974 Always resume download. If true is given, aria2 always tries to
975 resume download and if resume is not possible, aborts download.
976 If false is given, when all given URIs do not support resume or
977 aria2 encounters N URIs which does not support resume (N is the
978 value specified using --max-resume-failure-tries option), aria2
979 downloads file from scratch. See --max-resume-failure-tries op‐
980 tion. Default: true
981 --async-dns [true|false]
983 Enable asynchronous DNS. Default: true
984 --async-dns-server=<IPADDRESS>[,...]
986 Comma separated list of DNS server address used in asynchronous
987 DNS resolver. Usually asynchronous DNS resolver reads DNS server
988 addresses from /etc/resolv.conf. When this option is used, it
989 uses DNS servers specified in this option instead of ones in
990 /etc/resolv.conf. You can specify both IPv4 and IPv6 address.
991 This option is useful when the system does not have /etc/re‐
992 solv.conf and user does not have the permission to create it.
993 --auto-file-renaming [true|false]
995 Rename file name if the same file already exists. This option
996 works only in HTTP(S)/FTP download. The new file name has a dot
997 and a number(1..9999) appended after the name, but before the
998 file extension, if any. Default: true
999 --auto-save-interval=<SEC>
1001 Save a control file(*.aria2) every SEC seconds. If 0 is given,
1002 a control file is not saved during download. aria2 saves a con‐
1003 trol file when it stops regardless of the value. The possible
1004 values are between 0 to 600. Default: 60
1005 --conditional-get [true|false]
1007 Download file only when the local file is older than remote
1008 file. This function only works with HTTP(S) downloads only. It
1009 does not work if file size is specified in Metalink. It also ig‐
1010 nores Content-Disposition header. If a control file exists,
1011 this option will be ignored. This function uses If-Modi‐
1012 fied-Since header to get only newer file conditionally. When
1013 getting modification time of local file, it uses user supplied
1014 file name (see --out option) or file name part in URI if --out
1015 is not specified. To overwrite existing file, --allow-overwrite
1016 is required. Default: false
1017 --conf-path=<PATH>
1019 Change the configuration file path to PATH. Default:
1020 $HOME/.aria2/aria2.conf if present, otherwise $XDG_CON‐
1021 FIG_HOME/aria2/aria2.conf.
1022 --console-log-level=<LEVEL>
1024 Set log level to output to console. LEVEL is either debug,
1025 info, notice, warn or error. Default: notice
1026 --content-disposition-default-utf8 [true|false]
1028 Handle quoted string in Content-Disposition header as UTF-8 in‐
1029 stead of ISO-8859-1, for example, the filename parameter, but
1030 not the extended version filename*. Default: false
1031 -D, --daemon [true|false]
1033 Run as daemon. The current working directory will be changed to
1034 / and standard input, standard output and standard error will be
1035 redirected to /dev/null. Default: false
1036 --deferred-input [true|false]
1038 If true is given, aria2 does not read all URIs and options from
1039 file specified by --input-file option at startup, but it reads
1040 one by one when it needs later. This may reduce memory usage if
1041 input file contains a lot of URIs to download. If false is
1042 given, aria2 reads all URIs and options at startup. Default:
1043 false
1044 WARNING:
1046 --deferred-input option will be disabled when --save-session
1047 is used together.
1048 --disable-ipv6 [true|false]
1050 Disable IPv6. This is useful if you have to use broken DNS and
1051 want to avoid terribly slow AAAA record lookup. Default: false
1052 --disk-cache=<SIZE>
1054 Enable disk cache. If SIZE is 0, the disk cache is disabled.
1055 This feature caches the downloaded data in memory, which grows
1056 to at most SIZE bytes. The cache storage is created for aria2
1057 instance and shared by all downloads. The one advantage of the
1058 disk cache is reduce the disk I/O because the data are written
1059 in larger unit and it is reordered by the offset of the file.
1060 If hash checking is involved and the data are cached in memory,
1061 we don't need to read them from the disk. SIZE can include K or
1062 M (1K = 1024, 1M = 1024K). Default: 16M
1063 --download-result=<OPT>
1065 This option changes the way Download Results is formatted. If
1066 OPT is default, print GID, status, average download speed and
1067 path/URI. If multiple files are involved, path/URI of first re‐
1068 quested file is printed and remaining ones are omitted. If OPT
1069 is full, print GID, status, average download speed, percentage
1070 of progress and path/URI. The percentage of progress and
1071 path/URI are printed for each requested file in each row. If
1072 OPT is hide, Download Results is hidden. Default: default
1073 --dscp=<DSCP>
1075 Set DSCP value in outgoing IP packets of BitTorrent traffic for
1076 QoS. This parameter sets only DSCP bits in TOS field of IP pack‐
1077 ets, not the whole field. If you take values from /usr/in‐
1078 clude/netinet/ip.h divide them by 4 (otherwise values would be
1079 incorrect, e.g. your CS1 class would turn into CS4). If you take
1080 commonly used values from RFC, network vendors' documentation,
1081 Wikipedia or any other source, use them as they are.
1082 --rlimit-nofile=<NUM>
1084 Set the soft limit of open file descriptors. This open will
1085 only have effect when:
1086 a. The system supports it (posix)
1088 b. The limit does not exceed the hard limit.
1090 c. The specified limit is larger than the current soft limit.
1092 This is equivalent to setting nofile via ulimit, except that it
1094 will never decrease the limit.
1095 This option is only available on systems supporting the rlimit
1097 API.
1098 --enable-color [true|false]
1100 Enable color output for a terminal. Default: true
1101 --enable-mmap [true|false]
1103 Map files into memory. This option may not work if the file
1104 space is not pre-allocated. See --file-allocation.
1105 Default: false
1107 --event-poll=<POLL>
1109 Specify the method for polling events. The possible values are
1110 epoll, kqueue, port, poll and select. For each epoll, kqueue,
1111 port and poll, it is available if system supports it. epoll is
1112 available on recent Linux. kqueue is available on various *BSD
1113 systems including Mac OS X. port is available on Open Solaris.
1114 The default value may vary depending on the system you use.
1115 --file-allocation=<METHOD>
1117 Specify file allocation method. none doesn't pre-allocate file
1118 space. prealloc pre-allocates file space before download begins.
1119 This may take some time depending on the size of the file. If
1120 you are using newer file systems such as ext4 (with extents sup‐
1121 port), btrfs, xfs or NTFS(MinGW build only), falloc is your best
1122 choice. It allocates large(few GiB) files almost instantly.
1123 Don't use falloc with legacy file systems such as ext3 and FAT32
1124 because it takes almost same time as prealloc and it blocks
1125 aria2 entirely until allocation finishes. falloc may not be
1126 available if your system doesn't have posix_fallocate(3) func‐
1127 tion. trunc uses ftruncate(2) system call or platform-specific
1128 counterpart to truncate a file to a specified length.
1129 Possible Values: none, prealloc, trunc, falloc Default: prealloc
1131 WARNING:
1133 Using trunc seemingly allocates disk space very quickly, but
1134 what it actually does is that it sets file length metadata in
1135 file system, and does not allocate disk space at all. This
1136 means that it does not help avoiding fragmentation.
1137 NOTE:
1139 In multi file torrent downloads, the files adjacent forward
1140 to the specified files are also allocated if they share the
1141 same piece.
1142 --force-save [true|false]
1144 Save download with --save-session option even if the download is
1145 completed or removed. This option also saves control file in
1146 that situations. This may be useful to save BitTorrent seeding
1147 which is recognized as completed state. Default: false
1148 --save-not-found [true|false]
1150 Save download with --save-session option even if the file was
1151 not found on the server. This option also saves control file in
1152 that situations. Default: true
1153 --gid=<GID>
1155 Set GID manually. aria2 identifies each download by the ID
1156 called GID. The GID must be hex string of 16 characters, thus
1157 [0-9a-fA-F] are allowed and leading zeros must not be stripped.
1158 The GID all 0 is reserved and must not be used. The GID must be
1159 unique, otherwise error is reported and the download is not
1160 added. This option is useful when restoring the sessions saved
1161 using --save-session option. If this option is not used, new GID
1162 is generated by aria2.
1163 --hash-check-only [true|false]
1165 If true is given, after hash check using --check-integrity op‐
1166 tion, abort download whether or not download is complete. De‐
1167 fault: false
1168 --human-readable [true|false]
1170 Print sizes and speed in human readable format (e.g., 1.2Ki,
1171 3.4Mi) in the console readout. Default: true
1172 --interface=<INTERFACE>
1174 Bind sockets to given interface. You can specify interface name,
1175 IP address and host name. Possible Values: interface, IP ad‐
1176 dress, host name
1177 NOTE:
1179 If an interface has multiple addresses, it is highly recom‐
1180 mended to specify IP address explicitly. See also
1181 --disable-ipv6. If your system doesn't have getifaddrs(3),
1182 this option doesn't accept interface name.
1183 --keep-unfinished-download-result [true|false]
1185 Keep unfinished download results even if doing so exceeds
1186 --max-download-result. This is useful if all unfinished down‐
1187 loads must be saved in session file (see --save-session option).
1188 Please keep in mind that there is no upper bound to the number
1189 of unfinished download result to keep. If that is undesirable,
1190 turn this option off. Default: true
1191 --max-download-result=<NUM>
1193 Set maximum number of download result kept in memory. The down‐
1194 load results are completed/error/removed downloads. The download
1195 results are stored in FIFO queue and it can store at most NUM
1196 download results. When queue is full and new download result is
1197 created, oldest download result is removed from the front of the
1198 queue and new one is pushed to the back. Setting big number in
1199 this option may result high memory consumption after thousands
1200 of downloads. Specifying 0 means no download result is kept.
1201 Note that unfinished downloads are kept in memory regardless of
1202 this option value. See --keep-unfinished-download-result option.
1203 Default: 1000
1204 --max-mmap-limit=<SIZE>
1206 Set the maximum file size to enable mmap (see --enable-mmap op‐
1207 tion). The file size is determined by the sum of all files con‐
1208 tained in one download. For example, if a download contains 5
1209 files, then file size is the total size of those files. If file
1210 size is strictly greater than the size specified in this option,
1211 mmap will be disabled. Default: 9223372036854775807
1212 --max-resume-failure-tries=<N>
1214 When used with --always-resume=false, aria2 downloads file from
1215 scratch when aria2 detects N number of URIs that does not sup‐
1216 port resume. If N is 0, aria2 downloads file from scratch when
1217 all given URIs do not support resume. See --always-resume op‐
1218 tion. Default: 0
1219 --min-tls-version=<VERSION>
1221 Specify minimum SSL/TLS version to enable. Possible Values:
1222 TLSv1.1, TLSv1.2, TLSv1.3 Default: TLSv1.2
1223 --multiple-interface=<INTERFACES>
1225 Comma separated list of interfaces to bind sockets to. Requests
1226 will be splited among the interfaces to achieve link aggrega‐
1227 tion. You can specify interface name, IP address and hostname.
1228 If --interface is used, this option will be ignored. Possible
1229 Values: interface, IP address, hostname
1230 --log-level=<LEVEL>
1232 Set log level to output. LEVEL is either debug, info, notice,
1233 warn or error. Default: debug
1234 --on-bt-download-complete=<COMMAND>
1236 For BitTorrent, a command specified in --on-download-complete is
1237 called after download completed and seeding is over. On the
1238 other hand, this option set the command to be executed after
1239 download completed but before seeding. See Event Hook for more
1240 details about COMMAND. Possible Values: /path/to/command
1241 --on-download-complete=<COMMAND>
1243 Set the command to be executed after download completed. See
1244 Event Hook for more details about COMMAND. See also
1245 --on-download-stop option. Possible Values: /path/to/command
1246 --on-download-error=<COMMAND>
1248 Set the command to be executed after download aborted due to er‐
1249 ror. See Event Hook for more details about COMMAND. See also
1250 --on-download-stop option. Possible Values: /path/to/command
1251 --on-download-pause=<COMMAND>
1253 Set the command to be executed after download was paused. See
1254 Event Hook for more details about COMMAND. Possible Values:
1255 /path/to/command
1256 --on-download-start=<COMMAND>
1258 Set the command to be executed after download got started. See
1259 Event Hook for more details about COMMAND. Possible Values:
1260 /path/to/command
1261 --on-download-stop=<COMMAND>
1263 Set the command to be executed after download stopped. You can
1264 override the command to be executed for particular download re‐
1265 sult using --on-download-complete and --on-download-error. If
1266 they are specified, command specified in this option is not exe‐
1267 cuted. See Event Hook for more details about COMMAND. Possible
1268 Values: /path/to/command
1269 --optimize-concurrent-downloads [true|false|<A>:<B>]
1271 Optimizes the number of concurrent downloads according to the
1272 bandwidth available. aria2 uses the download speed observed in
1273 the previous downloads to adapt the number of downloads launched
1274 in parallel according to the rule N = A + B Log10(speed in
1275 Mbps). The coefficients A and B can be customized in the option
1276 arguments with A and B separated by a colon. The default values
1277 (A=5, B=25) lead to using typically 5 parallel downloads on
1278 1Mbps networks and above 50 on 100Mbps networks. The number of
1279 parallel downloads remains constrained under the maximum defined
1280 by the --max-concurrent-downloads parameter. Default: false
1281 --piece-length=<LENGTH>
1283 Set a piece length for HTTP/FTP downloads. This is the boundary
1284 when aria2 splits a file. All splits occur at multiple of this
1285 length. This option will be ignored in BitTorrent downloads. It
1286 will be also ignored if Metalink file contains piece hashes.
1287 Default: 1M
1288 NOTE:
1290 The possible use case of --piece-length option is change the
1291 request range in one HTTP pipelined request. To enable HTTP
1292 pipelining use --enable-http-pipelining.
1293 --show-console-readout [true|false]
1295 Show console readout. Default: true
1296 --stderr [true|false]
1298 Redirect all console output that would be otherwise printed in
1299 stdout to stderr. Default: false
1300 --summary-interval=<SEC>
1302 Set interval in seconds to output download progress summary.
1303 Setting 0 suppresses the output. Default: 60
1304 -Z, --force-sequential [true|false]
1306 Fetch URIs in the command-line sequentially and download each
1307 URI in a separate session, like the usual command-line download
1308 utilities. Default: false
1309 --max-overall-download-limit=<SPEED>
1311 Set max overall download speed in bytes/sec. 0 means unre‐
1312 stricted. You can append K or M (1K = 1024, 1M = 1024K). To
1313 limit the download speed per download, use --max-download-limit
1314 option. Default: 0
1315 --max-download-limit=<SPEED>
1317 Set max download speed per each download in bytes/sec. 0 means
1318 unrestricted. You can append K or M (1K = 1024, 1M = 1024K).
1319 To limit the overall download speed, use
1320 --max-overall-download-limit option. Default: 0
1321 --no-conf [true|false]
1323 Disable loading aria2.conf file.
1324 --no-file-allocation-limit=<SIZE>
1326 No file allocation is made for files whose size is smaller than
1327 SIZE. You can append K or M (1K = 1024, 1M = 1024K). Default:
1328 5M
1329 -P, --parameterized-uri [true|false]
1331 Enable parameterized URI support. You can specify set of parts:
1332 http://{sv1,sv2,sv3}/foo.iso. Also you can specify numeric se‐
1333 quences with step counter: http://host/image[000-100:2].img. A
1334 step counter can be omitted. If all URIs do not point to the
1335 same file, such as the second example above, -Z option is re‐
1336 quired. Default: false
1337 -q, --quiet [true|false]
1339 Make aria2 quiet (no console output). Default: false
1340 --realtime-chunk-checksum [true|false]
1342 Validate chunk of data by calculating checksum while downloading
1343 a file if chunk checksums are provided. Default: true
1344 --remove-control-file [true|false]
1346 Remove control file before download. Using with
1347 --allow-overwrite=true, download always starts from scratch.
1348 This will be useful for users behind proxy server which disables
1349 resume.
1350 --save-session=<FILE>
1352 Save error/unfinished downloads to FILE on exit. You can pass
1353 this output file to aria2c with --input-file option on restart.
1354 If you like the output to be gzipped append a .gz extension to
1355 the file name. Please note that downloads added by
1356 aria2.addTorrent() and aria2.addMetalink() RPC method and whose
1357 meta data could not be saved as a file are not saved. Downloads
1358 removed using aria2.remove() and aria2.forceRemove() will not be
1359 saved. GID is also saved with gid, but there are some restric‐
1360 tions, see below.
1361 NOTE:
1363 Normally, GID of the download itself is saved. But some down‐
1364 loads use meta data (e.g., BitTorrent and Metalink). In this
1365 case, there are some restrictions.
1366 magnet URI, and followed by torrent download
1368 GID of BitTorrent meta data download is saved.
1369 URI to torrent file, and followed by torrent download
1371 GID of torrent file download is saved.
1372 URI to metalink file, and followed by file downloads de‐
1374 scribed in metalink file
1375 GID of metalink file download is saved.
1376 local torrent file
1378 GID of torrent download is saved.
1379 local metalink file
1381 Any meaningful GID is not saved.
1382 --save-session-interval=<SEC>
1384 Save error/unfinished downloads to a file specified by
1385 --save-session option every SEC seconds. If 0 is given, file
1386 will be saved only when aria2 exits. Default: 0
1387 --socket-recv-buffer-size=<SIZE>
1389 Set the maximum socket receive buffer in bytes. Specifying 0
1390 will disable this option. This value will be set to socket file
1391 descriptor using SO_RCVBUF socket option with setsockopt() call.
1392 Default: 0
1393 --stop=<SEC>
1395 Stop application after SEC seconds has passed. If 0 is given,
1396 this feature is disabled. Default: 0
1397 --stop-with-process=<PID>
1399 Stop application when process PID is not running. This is use‐
1400 ful if aria2 process is forked from a parent process. The parent
1401 process can fork aria2 with its own pid and when parent process
1402 exits for some reason, aria2 can detect it and shutdown itself.
1403 --truncate-console-readout [true|false]
1405 Truncate console readout to fit in a single line. Default: true
1406 -v, --version
1408 Print the version number, copyright and the configuration infor‐
1409 mation and exit.
1410 Notes for Options
1412 Optional arguments
1413 The options that have its argument surrounded by square brackets([])
1414 take an optional argument. Usually omitting the argument is evaluated
1415 to true. If you use short form of these options(such as -V) and give
1416 an argument, then the option name and its argument should be concate‐
1417 nated(e.g. -Vfalse). If any spaces are inserted between the option
1418 name and the argument, the argument will be treated as URI and usually
1419 this is not what you expect.
1420 Units (K and M)
1422 Some options takes K and M to conveniently represent 1024 and 1048576
1423 respectively. aria2 detects these characters in case-insensitive way.
1424 In other words, k and m can be used as well as K and M respectively.
1425 URI, MAGNET, TORRENT_FILE, METALINK_FILE
1427 You can specify multiple URIs in command-line. Unless you specify
1428 --force-sequential option, all URIs must point to the same file or
1429 downloading will fail.
1430 You can specify arbitrary number of BitTorrent Magnet URI. Please note
1432 that they are always treated as a separate download. Both hex encoded
1433 40 characters Info Hash and Base32 encoded 32 characters Info Hash are
1434 supported. The multiple tr parameters are supported. Because BitTor‐
1435 rent Magnet URI is likely to contain & character, it is highly recom‐
1436 mended to always quote URI with single(') or double(") quotation. It
1437 is strongly recommended to enable DHT especially when tr parameter is
1438 missing. See http://www.bittorrent.org/beps/bep_0009.html for more de‐
1439 tails about BitTorrent Magnet URI.
1440 You can also specify arbitrary number of torrent files and Metalink
1442 documents stored on a local drive. Please note that they are always
1443 treated as a separate download. Both Metalink4 and Metalink version 3.0
1444 are supported.
1445 You can specify both torrent file with -T option and URIs. By doing
1447 this, you can download a file from both torrent swarm and
1448 HTTP(S)/FTP/SFTP server at the same time, while the data from
1449 HTTP(S)/FTP/SFTP are uploaded to the torrent swarm. For single file
1450 torrents, URI can be a complete URI pointing to the resource or if URI
1451 ends with /, name in torrent file in torrent is added. For multi-file
1452 torrents, name and path are added to form a URI for each file.
1453 NOTE:
1455 Make sure that URI is quoted with single(') or double(") quotation
1456 if it contains & or any characters that have special meaning in
1457 shell.
1458 Resuming Download
1460 Usually, you can resume transfer by just issuing same command (aria2c
1461 URI) if the previous transfer is made by aria2.
1462 If the previous transfer is made by a browser or wget like sequential
1464 download manager, then use --continue option to continue the transfer.
1465 Event Hook
1467 aria2 provides options to specify arbitrary command after specific
1468 event occurred. Currently following options are available:
1469 --on-bt-download-complete, --on-download-pause, --on-download-complete.
1470 --on-download-start, --on-download-error, --on-download-stop.
1471 aria2 passes 3 arguments to specified command when it is executed.
1473 These arguments are: GID, the number of files and file path. For HTTP,
1474 FTP, and SFTP downloads, usually the number of files is 1. BitTorrent
1475 download can contain multiple files. If number of files is more than
1476 one, file path is first one. In other words, this is the value of path
1477 key of first struct whose selected key is true in the response of
1478 aria2.getFiles() RPC method. If you want to get all file paths, con‐
1479 sider to use JSON-RPC/XML-RPC. Please note that file path may change
1480 during download in HTTP because of redirection or Content-Disposition
1481 header.
1482 Let's see an example of how arguments are passed to command:
1484 $ cat hook.sh
1486 #!/bin/sh
1487 echo "Called with [$1] [$2] [$3]"
1488 $ aria2c --on-download-complete hook.sh http://example.org/file.iso
1489 Called with [1] [1] [/path/to/file.iso]
1490
1492 Because aria2 can handle multiple downloads at once, it encounters lots
1493 of errors in a session. aria2 returns the following exit status based
1494 on the last error encountered.
1495 0 If all downloads were successful.
1497 1 If an unknown error occurred.
1499 2 If time out occurred.
1501 3 If a resource was not found.
1503 4 If aria2 saw the specified number of "resource not found" error.
1505 See --max-file-not-found option.
1506 5 If a download aborted because download speed was too slow. See
1508 --lowest-speed-limit option.
1509 6 If network problem occurred.
1511 7 If there were unfinished downloads. This error is only reported
1513 if all finished downloads were successful and there were unfin‐
1514 ished downloads in a queue when aria2 exited by pressing Ctrl-C
1515 by an user or sending TERM or INT signal.
1516 8 If remote server did not support resume when resume was required
1518 to complete download.
1519 9 If there was not enough disk space available.
1521 10 If piece length was different from one in .aria2 control file.
1523 See --allow-piece-length-change option.
1524 11 If aria2 was downloading same file at that moment.
1526 12 If aria2 was downloading same info hash torrent at that moment.
1528 13 If file already existed. See --allow-overwrite option.
1530 14 If renaming file failed. See --auto-file-renaming option.
1532 15 If aria2 could not open existing file.
1534 16 If aria2 could not create new file or truncate existing file.
1536 17 If file I/O error occurred.
1538 18 If aria2 could not create directory.
1540 19 If name resolution failed.
1542 20 If aria2 could not parse Metalink document.
1544 21 If FTP command failed.
1546 22 If HTTP response header was bad or unexpected.
1548 23 If too many redirects occurred.
1550 24 If HTTP authorization failed.
1552 25 If aria2 could not parse bencoded file (usually ".torrent"
1554 file).
1555 26 If ".torrent" file was corrupted or missing information that
1557 aria2 needed.
1558 27 If Magnet URI was bad.
1560 28 If bad/unrecognized option was given or unexpected option argu‐
1562 ment was given.
1563 29 If the remote server was unable to handle the request due to a
1565 temporary overloading or maintenance.
1566 30 If aria2 could not parse JSON-RPC request.
1568 31 Reserved. Not used.
1570 32 If checksum validation failed.
1572 NOTE:
1574 An error occurred in a finished download will not be reported as
1575 exit status.
1576
1578 aria2 recognizes the following environment variables.
1579 http_proxy [http://][USER:PASSWORD@]HOST[:PORT]
1581 Specify proxy server for use in HTTP. Overrides http-proxy
1582 value in configuration file. The command-line option
1583 --http-proxy overrides this value.
1584 https_proxy [http://][USER:PASSWORD@]HOST[:PORT]
1586 Specify proxy server for use in HTTPS. Overrides https-proxy
1587 value in configuration file. The command-line option
1588 --https-proxy overrides this value.
1589 ftp_proxy [http://][USER:PASSWORD@]HOST[:PORT]
1591 Specify proxy server for use in FTP. Overrides ftp-proxy value
1592 in configuration file. The command-line option --ftp-proxy
1593 overrides this value.
1594 all_proxy [http://][USER:PASSWORD@]HOST[:PORT]
1596 Specify proxy server for use if no protocol-specific proxy is
1597 specified. Overrides all-proxy value in configuration file.
1598 The command-line option --all-proxy overrides this value.
1599 NOTE:
1601 Although aria2 accepts ftp:// and https:// scheme in proxy URI, it
1602 simply assumes that http:// is specified and does not change its be‐
1603 havior based on the specified scheme.
1604 no_proxy [DOMAIN,...]
1606 Specify a comma-separated list of host names, domains and net‐
1607 work addresses with or without a subnet mask where no proxy
1608 should be used. Overrides the no-proxy value in configuration
1609 file. The command-line option --no-proxy overrides this value.
1610
1612 aria2.conf
1613 By default, aria2 checks whether the legacy path
1614 $HOME/.aria2/aria2.conf is present, otherwise it parses $XDG_CON‐
1615 FIG_HOME/aria2/aria2.conf as its configuration file. You can specify
1616 the path to configuration file using --conf-path option. If you don't
1617 want to use the configuration file, use --no-conf option.
1618 The configuration file is a text file and has 1 option per each line.
1620 In each line, you can specify name-value pair in the format:
1621 NAME=VALUE, where name is the long command-line option name without --
1622 prefix. You can use same syntax for the command-line option. The lines
1623 beginning # are treated as comments:
1624 # sample configuration file for aria2c
1626 listen-port=60000
1627 dht-listen-port=60000
1628 seed-ratio=1.0
1629 max-upload-limit=50K
1630 ftp-pasv=true
1631 NOTE:
1633 The confidential information such as user/password might be included
1634 in the configuration file. It is recommended to change file mode
1635 bits of the configuration file (e.g., chmod 600 aria2.conf), so that
1636 other user cannot see the contents of the file.
1637 The environment variables, such as ${HOME}, are expanded by shell.
1639 This means that those variables used in configuration file are not ex‐
1640 panded. However, it is useful to ${HOME} to refer user's home direc‐
1641 tory in configuration file to specify file paths. Therefore, aria2 ex‐
1642 pands ${HOME} found in the following option values to user's home di‐
1643 rectory:
1644 • ca-certificate
1646 • certificate
1648 • dht-file-path
1650 • dht-file-path6
1652 • dir
1654 • input-file
1656 • load-cookies
1658 • log
1660 • metalink-file
1662 • netrc-path
1664 • on-bt-download-complete
1666 • on-download-complete
1668 • on-download-error
1670 • on-download-start
1672 • on-download-stop
1674 • on-download-pause
1676 • out
1678 • private-key
1680 • rpc-certificate
1682 • rpc-private-key
1684 • save-cookies
1686 • save-session
1688 • server-stat-if
1690 • server-stat-of
1692 • torrent-file
1694 Note that this expansion occurs even if the above options are used in
1696 the command-line. This means that expansion may occur 2 times: first,
1697 shell and then aria2c.
1698 dht.dat
1700 Unless the legacy file paths $HOME/.aria2/dht.dat and
1701 $HOME/.aria2/dht6.dat are pointing to existing files, the routing table
1702 of IPv4 DHT is saved to the path $XDG_CACHE_HOME/aria2/dht.dat and the
1703 routing table of IPv6 DHT is saved to the path
1704 $XDG_CACHE_HOME/aria2/dht6.dat.
1705 Netrc
1707 Netrc support is enabled by default for HTTP(S)/FTP/SFTP. To disable
1708 netrc support, specify --no-netrc option. Your .netrc file should have
1709 correct permissions(600).
1710 If machine name starts ., aria2 performs domain-match instead of exact
1712 match. This is an extension of aria2. For example of domain match,
1713 imagine the following .netrc entry:
1714 machine .example.org login myid password mypasswd
1716 aria2.example.org domain-matches .example.org and uses myid and my‐
1718 passwd.
1719 Some domain-match example follow: example.net does not domain-match
1721 .example.org. example.org does not domain-match .example.org because of
1722 preceding .. If you want to match example.org, specify example.org.
1723 Control File
1725 aria2 uses a control file to track the progress of a download. A con‐
1726 trol file is placed in the same directory as the downloading file and
1727 its file name is the file name of downloading file with .aria2 ap‐
1728 pended. For example, if you are downloading file.zip, then the control
1729 file should be file.zip.aria2. (There is a exception for this naming
1730 convention. If you are downloading a multi torrent, its control file
1731 is the "top directory" name of the torrent with .aria2 appended. The
1732 "top directory" name is a value of "name" key in "info" directory in a
1733 torrent file.)
1734 Usually a control file is deleted once download completed. If aria2
1736 decides that download cannot be resumed(for example, when downloading a
1737 file from a HTTP server which doesn't support resume), a control file
1738 is not created.
1739 Normally if you lose a control file, you cannot resume download. But
1741 if you have a torrent or metalink with chunk checksums for the file,
1742 you can resume the download without a control file by giving -V option
1743 to aria2c in command-line.
1744 Input File
1746 The input file can contain a list of URIs for aria2 to download. You
1747 can specify multiple URIs for a single entity: separate URIs on a sin‐
1748 gle line using the TAB character.
1749 Each line is treated as if it is provided in command-line argument.
1751 Therefore they are affected by --force-sequential and
1752 --parameterized-uri options.
1753 Since URIs in the input file are directly read by aria2, they must not
1755 be quoted with single(') or double(") quotation.
1756 Lines starting with # are treated as comments and skipped.
1758 Additionally, the following options can be specified after each line of
1760 URIs. These optional lines must start with white space(s).
1761 • all-proxy
1763 • all-proxy-passwd
1765 • all-proxy-user
1767 • allow-overwrite
1769 • allow-piece-length-change
1771 • always-resume
1773 • async-dns
1775 • auto-file-renaming
1777 • bt-enable-hook-after-hash-check
1779 • bt-enable-lpd
1781 • bt-exclude-tracker
1783 • bt-external-ip
1785 • bt-force-encryption
1787 • bt-hash-check-seed
1789 • bt-load-saved-metadata
1791 • bt-max-peers
1793 • bt-metadata-only
1795 • bt-min-crypto-level
1797 • bt-prioritize-piece
1799 • bt-remove-unselected-file
1801 • bt-request-peer-speed-limit
1803 • bt-require-crypto
1805 • bt-save-metadata
1807 • bt-seed-unverified
1809 • bt-stop-timeout
1811 • bt-tracker
1813 • bt-tracker-connect-timeout
1815 • bt-tracker-interval
1817 • bt-tracker-timeout
1819 • check-integrity
1821 • checksum
1823 • conditional-get
1825 • connect-timeout
1827 • content-disposition-default-utf8
1829 • continue
1831 • dir
1833 • dry-run
1835 • enable-http-keep-alive
1837 • enable-http-pipelining
1839 • enable-mmap
1841 • enable-peer-exchange
1843 • file-allocation
1845 • follow-metalink
1847 • follow-torrent
1849 • force-save
1851 • ftp-passwd
1853 • ftp-pasv
1855 • ftp-proxy
1857 • ftp-proxy-passwd
1859 • ftp-proxy-user
1861 • ftp-reuse-connection
1863 • ftp-type
1865 • ftp-user
1867 • gid
1869 • hash-check-only
1871 • header
1873 • http-accept-gzip
1875 • http-auth-challenge
1877 • http-no-cache
1879 • http-passwd
1881 • http-proxy
1883 • http-proxy-passwd
1885 • http-proxy-user
1887 • http-user
1889 • https-proxy
1891 • https-proxy-passwd
1893 • https-proxy-user
1895 • index-out
1897 • lowest-speed-limit
1899 • max-connection-per-server
1901 • max-download-limit
1903 • max-file-not-found
1905 • max-mmap-limit
1907 • max-resume-failure-tries
1909 • max-tries
1911 • max-upload-limit
1913 • metalink-base-uri
1915 • metalink-enable-unique-protocol
1917 • metalink-language
1919 • metalink-location
1921 • metalink-os
1923 • metalink-preferred-protocol
1925 • metalink-version
1927 • min-split-size
1929 • no-file-allocation-limit
1931 • no-netrc
1933 • no-proxy
1935 • out
1937 • parameterized-uri
1939 • pause
1941 • pause-metadata
1943 • piece-length
1945 • proxy-method
1947 • realtime-chunk-checksum
1949 • referer
1951 • remote-time
1953 • remove-control-file
1955 • retry-wait
1957 • reuse-uri
1959 • rpc-save-upload-metadata
1961 • seed-ratio
1963 • seed-time
1965 • select-file
1967 • split
1969 • ssh-host-key-md
1971 • stream-piece-selector
1973 • timeout
1975 • uri-selector
1977 • use-head
1979 • user-agent
1981 These options have exactly same meaning of the ones in the command-line
1983 options, but it just applies to the URIs it belongs to. Please note
1984 that for options in input file -- prefix must be stripped.
1985 For example, the content of uri.txt is:
1987 http://server/file.iso http://mirror/file.iso
1989 dir=/iso_images
1990 out=file.img
1991 http://foo/bar
1992 If aria2 is executed with -i uri.txt -d /tmp options, then file.iso is
1994 saved as /iso_images/file.img and it is downloaded from
1995 http://server/file.iso and http://mirror/file.iso. The file bar is
1996 downloaded from http://foo/bar and saved as /tmp/bar.
1997 In some cases, out parameter has no effect. See note of --out option
1999 for the restrictions.
2000 Server Performance Profile
2002 This section describes the format of server performance profile. The
2003 file is plain text and each line has several NAME=VALUE pair, delimited
2004 by comma. Currently following NAMEs are recognized:
2005 host Host name of the server. Required.
2007 protocol
2009 Protocol for this profile, such as ftp, http. Required.
2010 dl_speed
2012 The average download speed observed in the previous download in
2013 bytes per sec. Required.
2014 sc_avg_speed
2016 The average download speed observed in the previous download in
2017 bytes per sec. This value is only updated if the download is
2018 done in single connection environment and only used by Adap‐
2019 tiveURISelector. Optional.
2020 mc_avg_speed
2022 The average download speed observed in the previous download in
2023 bytes per sec. This value is only updated if the download is
2024 done in multi connection environment and only used by Adap‐
2025 tiveURISelector. Optional.
2026 counter
2028 How many times the server is used. Currently this value is only
2029 used by AdaptiveURISelector. Optional.
2030 last_updated
2032 Last contact time in GMT with this server, specified in the sec‐
2033 onds since the Epoch(00:00:00 on January 1, 1970, UTC). Re‐
2034 quired.
2035 status ERROR is set when server cannot be reached or out-of-service or
2037 timeout occurred. Otherwise, OK is set.
2038 Those fields must exist in one line. The order of the fields is not
2040 significant. You can put pairs other than the above; they are simply
2041 ignored.
2042 An example follows:
2044 host=localhost, protocol=http, dl_speed=32000, last_updated=1222491640, status=OK
2046 host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR
2047
2049 aria2 provides JSON-RPC over HTTP and XML-RPC over HTTP interfaces that
2050 offer basically the same functionality. aria2 also provides JSON-RPC
2051 over WebSocket. JSON-RPC over WebSocket uses the same method signatures
2052 and response format as JSON-RPC over HTTP, but additionally provides
2053 server-initiated notifications. See JSON-RPC over WebSocket section for
2054 more information.
2055 The request path of the JSON-RPC interface (for both over HTTP and over
2057 WebSocket) is /jsonrpc. The request path of the XML-RPC interface is
2058 /rpc.
2059 The WebSocket URI for JSON-RPC over WebSocket is ws://HOST:PORT/json‐
2061 rpc. If you enabled SSL/TLS encryption, use wss://HOST:PORT/jsonrpc in‐
2062 stead.
2063 The implemented JSON-RPC is based on JSON-RPC 2.0 <‐
2065 http://jsonrpc.org/specification>, and supports HTTP POST and GET
2066 (JSONP). The WebSocket transport is an aria2 extension.
2067 The JSON-RPC interface does not support notifications over HTTP, but
2069 the RPC server will send notifications over WebSocket. It also does not
2070 support floating point numbers. The character encoding must be UTF-8.
2071 When reading the following documentation for JSON-RPC, interpret
2073 structs as JSON objects.
2074 Terminology
2076 GID
2077 The GID (or gid) is a key to manage each download. Each download
2078 will be assigned a unique GID. The GID is stored as 64-bit binary
2079 value in aria2. For RPC access, it is represented as a hex string
2080 of 16 characters (e.g., 2089b05ecca3d829). Normally, aria2 generates
2081 this GID for each download, but the user can specify GIDs manually
2082 using the --gid option. When querying downloads by GID, you can
2083 specify only the prefix of a GID as long as it is unique among oth‐
2084 ers.
2085 RPC authorization secret token
2087 As of 1.18.4, in addition to HTTP basic authorization, aria2 provides
2088 RPC method-level authorization. In a future release, HTTP basic autho‐
2089 rization will be removed and RPC method-level authorization will become
2090 mandatory.
2091 To use RPC method-level authorization, the user has to specify an RPC
2093 secret authorization token using the --rpc-secret option. For each RPC
2094 method call, the caller has to include the token prefixed with token:.
2095 Even when the --rpc-secret option is not used, if the first parameter
2096 in the RPC method is a string and starts with token:, it will removed
2097 from the parameter list before the request is being processed.
2098 For example, if the RPC secret authorization token is $$secret$$, call‐
2100 ing aria2.addUri RPC method would have to look like this:
2101 aria2.addUri("token:$$secret$$", ["http://example.org/file"])
2103 The system.multicall RPC method is treated specially. Since the XML-RPC
2105 specification only allows a single array as a parameter for this
2106 method, we don't specify the token in the call. Instead, each nested
2107 method call has to provide the token as the first parameter as de‐
2108 scribed above.
2109 NOTE:
2111 The secret token validation in aria2 is designed to take at least a
2112 certain amount of time to mitigate brute-force/dictionary attacks
2113 against the RPC interface. Therefore it is recommended to prefer
2114 Batch or system.multicall requests when appropriate.
2115 system.listMethods and system.listNotifications can be executed
2117 without token. Since they just return available methods/notifica‐
2118 tions, they do not alter anything, they're safe without secret to‐
2119 ken.
2120 Methods
2122 All code examples are compatible with the Python 2.7 interpreter. For
2123 information on the secret parameter, see RPC authorization secret to‐
2124 ken.
2125 aria2.addUri([secret], uris[, options[, position]])
2127 This method adds a new download. uris is an array of
2128 HTTP/FTP/SFTP/BitTorrent URIs (strings) pointing to the same re‐
2129 source. If you mix URIs pointing to different resources, then
2130 the download may fail or be corrupted without aria2 complaining.
2131 When adding BitTorrent Magnet URIs, uris must have only one ele‐
2132 ment and it should be BitTorrent Magnet URI. options is a
2133 struct and its members are pairs of option name and value. See
2134 Options below for more details. If position is given, it must
2135 be an integer starting from 0. The new download will be inserted
2136 at position in the waiting queue. If position is omitted or po‐
2137 sition is larger than the current size of the queue, the new
2138 download is appended to the end of the queue. This method re‐
2139 turns the GID of the newly registered download.
2140 JSON-RPC Example
2142 The following example adds http://example.org/file:
2144 >>> import urllib2, json
2146 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2147 ... 'method':'aria2.addUri',
2148 ... 'params':[['http://example.org/file']]})
2149 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2150 >>> c.read()
2151 '{"id":"qwer","jsonrpc":"2.0","result":"2089b05ecca3d829"}'
2152 XML-RPC Example
2154 The following example adds http://example.org/file:
2156 >>> import xmlrpclib
2158 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2159 >>> s.aria2.addUri(['http://example.org/file'])
2160 '2089b05ecca3d829'
2161 The following example adds a new download with two sources and
2163 some options:
2164 >>> s.aria2.addUri(['http://example.org/file', 'http://mirror/file'],
2166 dict(dir="/tmp"))
2167 'd2703803b52216d1'
2168 The following example adds a download and inserts it to the
2170 front of the queue:
2171 >>> s.aria2.addUri(['http://example.org/file'], {}, 0)
2173 'ca3d829cee549a4d'
2174 aria2.addTorrent([secret], torrent[, uris[, options[, position]]])
2176 This method adds a BitTorrent download by uploading a ".torrent"
2177 file. If you want to add a BitTorrent Magnet URI, use the
2178 aria2.addUri() method instead. torrent must be a base64-encoded
2179 string containing the contents of the ".torrent" file. uris is
2180 an array of URIs (string). uris is used for Web-seeding. For
2181 single file torrents, the URI can be a complete URI pointing to
2182 the resource; if URI ends with /, name in torrent file is added.
2183 For multi-file torrents, name and path in torrent are added to
2184 form a URI for each file. options is a struct and its members
2185 are pairs of option name and value. See Options below for more
2186 details. If position is given, it must be an integer starting
2187 from 0. The new download will be inserted at position in the
2188 waiting queue. If position is omitted or position is larger than
2189 the current size of the queue, the new download is appended to
2190 the end of the queue. This method returns the GID of the newly
2191 registered download. If --rpc-save-upload-metadata is true, the
2192 uploaded data is saved as a file named as the hex string of
2193 SHA-1 hash of data plus ".torrent" in the directory specified by
2194 --dir option. E.g. a file name might be
2195 0a3893293e27ac0490424c06de4d09242215f0a6.torrent. If a file
2196 with the same name already exists, it is overwritten! If the
2197 file cannot be saved successfully or --rpc-save-upload-metadata
2198 is false, the downloads added by this method are not saved by
2199 --save-session.
2200 The following examples add local file file.torrent.
2202 JSON-RPC Example
2204 >>> import urllib2, json, base64
2206 >>> torrent = base64.b64encode(open('file.torrent').read())
2207 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'asdf',
2208 ... 'method':'aria2.addTorrent', 'params':[torrent]})
2209 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2210 >>> c.read()
2211 '{"id":"asdf","jsonrpc":"2.0","result":"2089b05ecca3d829"}'
2212 XML-RPC Example
2214 >>> import xmlrpclib
2216 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2217 >>> s.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent', mode='rb').read()))
2218 '2089b05ecca3d829'
2219 aria2.addMetalink([secret], metalink[, options[, position]])
2221 This method adds a Metalink download by uploading a ".metalink"
2222 file. metalink is a base64-encoded string which contains the
2223 contents of the ".metalink" file. options is a struct and its
2224 members are pairs of option name and value. See Options below
2225 for more details. If position is given, it must be an integer
2226 starting from 0. The new download will be inserted at position
2227 in the waiting queue. If position is omitted or position is
2228 larger than the current size of the queue, the new download is
2229 appended to the end of the queue. This method returns an array
2230 of GIDs of newly registered downloads. If
2231 --rpc-save-upload-metadata is true, the uploaded data is saved
2232 as a file named hex string of SHA-1 hash of data plus ".met‐
2233 alink" in the directory specified by --dir option. E.g. a file
2234 name might be 0a3893293e27ac0490424c06de4d09242215f0a6.metalink.
2235 If a file with the same name already exists, it is overwritten!
2236 If the file cannot be saved successfully or
2237 --rpc-save-upload-metadata is false, the downloads added by this
2238 method are not saved by --save-session.
2239 The following examples add local file file.meta4.
2241 JSON-RPC Example
2243 >>> import urllib2, json, base64
2245 >>> metalink = base64.b64encode(open('file.meta4').read())
2246 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2247 ... 'method':'aria2.addMetalink',
2248 ... 'params':[metalink]})
2249 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2250 >>> c.read()
2251 '{"id":"qwer","jsonrpc":"2.0","result":["2089b05ecca3d829"]}'
2252 XML-RPC Example
2254 >>> import xmlrpclib
2256 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2257 >>> s.aria2.addMetalink(xmlrpclib.Binary(open('file.meta4', mode='rb').read()))
2258 ['2089b05ecca3d829']
2259 aria2.remove([secret], gid)
2261 This method removes the download denoted by gid (string). If
2262 the specified download is in progress, it is first stopped. The
2263 status of the removed download becomes removed. This method re‐
2264 turns GID of removed download.
2265 The following examples remove a download with
2267 GID#2089b05ecca3d829.
2268 JSON-RPC Example
2270 >>> import urllib2, json
2272 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2273 ... 'method':'aria2.remove',
2274 ... 'params':['2089b05ecca3d829']})
2275 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2276 >>> c.read()
2277 '{"id":"qwer","jsonrpc":"2.0","result":"2089b05ecca3d829"}'
2278 XML-RPC Example
2280 >>> import xmlrpclib
2282 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2283 >>> s.aria2.remove('2089b05ecca3d829')
2284 '2089b05ecca3d829'
2285 aria2.forceRemove([secret], gid)
2287 This method removes the download denoted by gid. This method
2288 behaves just like aria2.remove() except that this method removes
2289 the download without performing any actions which take time,
2290 such as contacting BitTorrent trackers to unregister the down‐
2291 load first.
2292 aria2.pause([secret], gid)
2294 This method pauses the download denoted by gid (string). The
2295 status of paused download becomes paused. If the download was
2296 active, the download is placed in the front of waiting queue.
2297 While the status is paused, the download is not started. To
2298 change status to waiting, use the aria2.unpause() method. This
2299 method returns GID of paused download.
2300 aria2.pauseAll([secret])
2302 This method is equal to calling aria2.pause() for every ac‐
2303 tive/waiting download. This methods returns OK.
2304 aria2.forcePause([secret], gid)
2306 This method pauses the download denoted by gid. This method be‐
2307 haves just like aria2.pause() except that this method pauses
2308 downloads without performing any actions which take time, such
2309 as contacting BitTorrent trackers to unregister the download
2310 first.
2311 aria2.forcePauseAll([secret])
2313 This method is equal to calling aria2.forcePause() for every ac‐
2314 tive/waiting download. This methods returns OK.
2315 aria2.unpause([secret], gid)
2317 This method changes the status of the download denoted by gid
2318 (string) from paused to waiting, making the download eligible to
2319 be restarted. This method returns the GID of the unpaused down‐
2320 load.
2321 aria2.unpauseAll([secret])
2323 This method is equal to calling aria2.unpause() for every paused
2324 download. This methods returns OK.
2325 aria2.tellStatus([secret], gid[, keys])
2327 This method returns the progress of the download denoted by gid
2328 (string). keys is an array of strings. If specified, the re‐
2329 sponse contains only keys in the keys array. If keys is empty or
2330 omitted, the response contains all keys. This is useful when you
2331 just want specific keys and avoid unnecessary transfers. For
2332 example, aria2.tellStatus("2089b05ecca3d829", ["gid", "status"])
2333 returns the gid and status keys only. The response is a struct
2334 and contains following keys. Values are strings.
2335 gid GID of the download.
2337 status active for currently downloading/seeding downloads.
2339 waiting for downloads in the queue; download is not
2340 started. paused for paused downloads. error for down‐
2341 loads that were stopped because of error. complete for
2342 stopped and completed downloads. removed for the down‐
2343 loads removed by user.
2344 totalLength
2346 Total length of the download in bytes.
2347 completedLength
2349 Completed length of the download in bytes.
2350 uploadLength
2352 Uploaded length of the download in bytes.
2353 bitfield
2355 Hexadecimal representation of the download progress. The
2356 highest bit corresponds to the piece at index 0. Any set
2357 bits indicate loaded pieces, while unset bits indicate
2358 not yet loaded and/or missing pieces. Any overflow bits
2359 at the end are set to zero. When the download was not
2360 started yet, this key will not be included in the re‐
2361 sponse.
2362 downloadSpeed
2364 Download speed of this download measured in bytes/sec.
2365 uploadSpeed
2367 Upload speed of this download measured in bytes/sec.
2368 infoHash
2370 InfoHash. BitTorrent only.
2371 numSeeders
2373 The number of seeders aria2 has connected to. BitTorrent
2374 only.
2375 seeder true if the local endpoint is a seeder. Otherwise false.
2377 BitTorrent only.
2378 pieceLength
2380 Piece length in bytes.
2381 numPieces
2383 The number of pieces.
2384 connections
2386 The number of peers/servers aria2 has connected to.
2387 errorCode
2389 The code of the last error for this item, if any. The
2390 value is a string. The error codes are defined in the
2391 EXIT STATUS section. This value is only available for
2392 stopped/completed downloads.
2393 errorMessage
2395 The (hopefully) human readable error message associated
2396 to errorCode.
2397 followedBy
2399 List of GIDs which are generated as the result of this
2400 download. For example, when aria2 downloads a Metalink
2401 file, it generates downloads described in the Metalink
2402 (see the --follow-metalink option). This value is useful
2403 to track auto-generated downloads. If there are no such
2404 downloads, this key will not be included in the response.
2405 following
2407 The reverse link for followedBy. A download included in
2408 followedBy has this object's GID in its following value.
2409 belongsTo
2411 GID of a parent download. Some downloads are a part of
2412 another download. For example, if a file in a Metalink
2413 has BitTorrent resources, the downloads of ".torrent"
2414 files are parts of that parent. If this download has no
2415 parent, this key will not be included in the response.
2416 dir Directory to save files.
2418 files Returns the list of files. The elements of this list are
2420 the same structs used in aria2.getFiles() method.
2421 bittorrent
2423 Struct which contains information retrieved from the
2424 .torrent (file). BitTorrent only. It contains following
2425 keys.
2426 announceList
2428 List of lists of announce URIs. If the torrent
2429 contains announce and no announce-list, announce
2430 is converted to the announce-list format.
2431 comment
2433 The comment of the torrent. comment.utf-8 is used
2434 if available.
2435 creationDate
2437 The creation time of the torrent. The value is an
2438 integer since the epoch, measured in seconds.
2439 mode File mode of the torrent. The value is either sin‐
2441 gle or multi.
2442 info Struct which contains data from Info dictionary.
2444 It contains following keys.
2445 name name in info dictionary. name.utf-8 is used
2447 if available.
2448 verifiedLength
2450 The number of verified number of bytes while the files
2451 are being hash checked. This key exists only when this
2452 download is being hash checked.
2453 verifyIntegrityPending
2455 true if this download is waiting for the hash check in a
2456 queue. This key exists only when this download is in the
2457 queue.
2458 JSON-RPC Example
2460 The following example gets information about a download with
2462 GID#2089b05ecca3d829:
2463 >>> import urllib2, json
2465 >>> from pprint import pprint
2466 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2467 ... 'method':'aria2.tellStatus',
2468 ... 'params':['2089b05ecca3d829']})
2469 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2470 >>> pprint(json.loads(c.read()))
2471 {u'id': u'qwer',
2472 u'jsonrpc': u'2.0',
2473 u'result': {u'bitfield': u'0000000000',
2474 u'completedLength': u'901120',
2475 u'connections': u'1',
2476 u'dir': u'/downloads',
2477 u'downloadSpeed': u'15158',
2478 u'files': [{u'index': u'1',
2479 u'length': u'34896138',
2480 u'completedLength': u'34896138',
2481 u'path': u'/downloads/file',
2482 u'selected': u'true',
2483 u'uris': [{u'status': u'used',
2484 u'uri': u'http://example.org/file'}]}],
2485 u'gid': u'2089b05ecca3d829',
2486 u'numPieces': u'34',
2487 u'pieceLength': u'1048576',
2488 u'status': u'active',
2489 u'totalLength': u'34896138',
2490 u'uploadLength': u'0',
2491 u'uploadSpeed': u'0'}}
2492 The following example gets only specific keys:
2494 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2496 ... 'method':'aria2.tellStatus',
2497 ... 'params':['2089b05ecca3d829',
2498 ... ['gid',
2499 ... 'totalLength',
2500 ... 'completedLength']]})
2501 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2502 >>> pprint(json.loads(c.read()))
2503 {u'id': u'qwer',
2504 u'jsonrpc': u'2.0',
2505 u'result': {u'completedLength': u'5701632',
2506 u'gid': u'2089b05ecca3d829',
2507 u'totalLength': u'34896138'}}
2508 XML-RPC Example
2510 The following example gets information about a download with
2512 GID#2089b05ecca3d829:
2513 >>> import xmlrpclib
2515 >>> from pprint import pprint
2516 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2517 >>> r = s.aria2.tellStatus('2089b05ecca3d829')
2518 >>> pprint(r)
2519 {'bitfield': 'ffff80',
2520 'completedLength': '34896138',
2521 'connections': '0',
2522 'dir': '/downloads',
2523 'downloadSpeed': '0',
2524 'errorCode': '0',
2525 'files': [{'index': '1',
2526 'length': '34896138',
2527 'completedLength': '34896138',
2528 'path': '/downloads/file',
2529 'selected': 'true',
2530 'uris': [{'status': 'used',
2531 'uri': 'http://example.org/file'}]}],
2532 'gid': '2089b05ecca3d829',
2533 'numPieces': '17',
2534 'pieceLength': '2097152',
2535 'status': 'complete',
2536 'totalLength': '34896138',
2537 'uploadLength': '0',
2538 'uploadSpeed': '0'}
2539 The following example gets only specific keys:
2541 >>> r = s.aria2.tellStatus('2089b05ecca3d829', ['gid', 'totalLength', 'completedLength'])
2543 >>> pprint(r)
2544 {'completedLength': '34896138', 'gid': '2089b05ecca3d829', 'totalLength': '34896138'}
2545 aria2.getUris([secret], gid)
2547 This method returns the URIs used in the download denoted by gid
2548 (string). The response is an array of structs and it contains
2549 following keys. Values are string.
2550 uri URI
2552 status 'used' if the URI is in use. 'waiting' if the URI is
2554 still waiting in the queue.
2555 JSON-RPC Example
2557 >>> import urllib2, json
2559 >>> from pprint import pprint
2560 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2561 ... 'method':'aria2.getUris',
2562 ... 'params':['2089b05ecca3d829']})
2563 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2564 >>> pprint(json.loads(c.read()))
2565 {u'id': u'qwer',
2566 u'jsonrpc': u'2.0',
2567 u'result': [{u'status': u'used',
2568 u'uri': u'http://example.org/file'}]}
2569 XML-RPC Example
2571 >>> import xmlrpclib
2573 >>> from pprint import pprint
2574 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2575 >>> r = s.aria2.getUris('2089b05ecca3d829')
2576 >>> pprint(r)
2577 [{'status': 'used', 'uri': 'http://example.org/file'}]
2578 aria2.getFiles([secret], gid)
2580 This method returns the file list of the download denoted by gid
2581 (string). The response is an array of structs which contain
2582 following keys. Values are strings.
2583 index Index of the file, starting at 1, in the same order as
2585 files appear in the multi-file torrent.
2586 path File path.
2588 length File size in bytes.
2590 completedLength
2592 Completed length of this file in bytes. Please note that
2593 it is possible that sum of completedLength is less than
2594 the completedLength returned by the aria2.tellStatus()
2595 method. This is because completedLength in
2596 aria2.getFiles() only includes completed pieces. On the
2597 other hand, completedLength in aria2.tellStatus() also
2598 includes partially completed pieces.
2599 selected
2601 true if this file is selected by --select-file option. If
2602 --select-file is not specified or this is single-file
2603 torrent or not a torrent download at all, this value is
2604 always true. Otherwise false.
2605 uris Returns a list of URIs for this file. The element type is
2607 the same struct used in the aria2.getUris() method.
2608 JSON-RPC Example
2610 >>> import urllib2, json
2612 >>> from pprint import pprint
2613 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2614 ... 'method':'aria2.getFiles',
2615 ... 'params':['2089b05ecca3d829']})
2616 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2617 >>> pprint(json.loads(c.read()))
2618 {u'id': u'qwer',
2619 u'jsonrpc': u'2.0',
2620 u'result': [{u'index': u'1',
2621 u'length': u'34896138',
2622 u'completedLength': u'34896138',
2623 u'path': u'/downloads/file',
2624 u'selected': u'true',
2625 u'uris': [{u'status': u'used',
2626 u'uri': u'http://example.org/file'}]}]}
2627 XML-RPC Example
2629 >>> import xmlrpclib
2631 >>> from pprint import pprint
2632 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2633 >>> r = s.aria2.getFiles('2089b05ecca3d829')
2634 >>> pprint(r)
2635 [{'index': '1',
2636 'length': '34896138',
2637 'completedLength': '34896138',
2638 'path': '/downloads/file',
2639 'selected': 'true',
2640 'uris': [{'status': 'used',
2641 'uri': 'http://example.org/file'}]}]
2642 aria2.getPeers([secret], gid)
2644 This method returns a list peers of the download denoted by gid
2645 (string). This method is for BitTorrent only. The response is
2646 an array of structs and contains the following keys. Values are
2647 strings.
2648 peerId Percent-encoded peer ID.
2650 ip IP address of the peer.
2652 port Port number of the peer.
2654 bitfield
2656 Hexadecimal representation of the download progress of
2657 the peer. The highest bit corresponds to the piece at in‐
2658 dex 0. Set bits indicate the piece is available and unset
2659 bits indicate the piece is missing. Any spare bits at the
2660 end are set to zero.
2661 amChoking
2663 true if aria2 is choking the peer. Otherwise false.
2664 peerChoking
2666 true if the peer is choking aria2. Otherwise false.
2667 downloadSpeed
2669 Download speed (byte/sec) that this client obtains from
2670 the peer.
2671 uploadSpeed
2673 Upload speed(byte/sec) that this client uploads to the
2674 peer.
2675 seeder true if this peer is a seeder. Otherwise false.
2677 JSON-RPC Example
2679 >>> import urllib2, json
2681 >>> from pprint import pprint
2682 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2683 ... 'method':'aria2.getPeers',
2684 ... 'params':['2089b05ecca3d829']})
2685 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2686 >>> pprint(json.loads(c.read()))
2687 {u'id': u'qwer',
2688 u'jsonrpc': u'2.0',
2689 u'result': [{u'amChoking': u'true',
2690 u'bitfield': u'ffffffffffffffffffffffffffffffffffffffff',
2691 u'downloadSpeed': u'10602',
2692 u'ip': u'10.0.0.9',
2693 u'peerChoking': u'false',
2694 u'peerId': u'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6',
2695 u'port': u'6881',
2696 u'seeder': u'true',
2697 u'uploadSpeed': u'0'},
2698 {u'amChoking': u'false',
2699 u'bitfield': u'ffffeff0fffffffbfffffff9fffffcfff7f4ffff',
2700 u'downloadSpeed': u'8654',
2701 u'ip': u'10.0.0.30',
2702 u'peerChoking': u'false',
2703 u'peerId': u'bittorrent client758',
2704 u'port': u'37842',
2705 u'seeder': u'false',
2706 u'uploadSpeed': u'6890'}]}
2707 XML-RPC Example
2709 >>> import xmlrpclib
2711 >>> from pprint import pprint
2712 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2713 >>> r = s.aria2.getPeers('2089b05ecca3d829')
2714 >>> pprint(r)
2715 [{'amChoking': 'true',
2716 'bitfield': 'ffffffffffffffffffffffffffffffffffffffff',
2717 'downloadSpeed': '10602',
2718 'ip': '10.0.0.9',
2719 'peerChoking': 'false',
2720 'peerId': 'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6',
2721 'port': '6881',
2722 'seeder': 'true',
2723 'uploadSpeed': '0'},
2724 {'amChoking': 'false',
2725 'bitfield': 'ffffeff0fffffffbfffffff9fffffcfff7f4ffff',
2726 'downloadSpeed': '8654',
2727 'ip': '10.0.0.30',
2728 'peerChoking': 'false',
2729 'peerId': 'bittorrent client758',
2730 'port': '37842',
2731 'seeder': 'false,
2732 'uploadSpeed': '6890'}]
2733 aria2.getServers([secret], gid)
2735 This method returns currently connected HTTP(S)/FTP/SFTP servers
2736 of the download denoted by gid (string). The response is an ar‐
2737 ray of structs and contains the following keys. Values are
2738 strings.
2739 index Index of the file, starting at 1, in the same order as
2741 files appear in the multi-file metalink.
2742 servers
2744 A list of structs which contain the following keys.
2745 uri Original URI.
2747 currentUri
2749 This is the URI currently used for downloading. If
2750 redirection is involved, currentUri and uri may
2751 differ.
2752 downloadSpeed
2754 Download speed (byte/sec)
2755 JSON-RPC Example
2757 >>> import urllib2, json
2759 >>> from pprint import pprint
2760 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2761 ... 'method':'aria2.getServers',
2762 ... 'params':['2089b05ecca3d829']})
2763 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2764 >>> pprint(json.loads(c.read()))
2765 {u'id': u'qwer',
2766 u'jsonrpc': u'2.0',
2767 u'result': [{u'index': u'1',
2768 u'servers': [{u'currentUri': u'http://example.org/file',
2769 u'downloadSpeed': u'10467',
2770 u'uri': u'http://example.org/file'}]}]}
2771 XML-RPC Example
2773 >>> import xmlrpclib
2775 >>> from pprint import pprint
2776 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2777 >>> r = s.aria2.getServers('2089b05ecca3d829')
2778 >>> pprint(r)
2779 [{'index': '1',
2780 'servers': [{'currentUri': 'http://example.org/dl/file',
2781 'downloadSpeed': '20285',
2782 'uri': 'http://example.org/file'}]}]
2783 aria2.tellActive([secret][, keys])
2785 This method returns a list of active downloads. The response is
2786 an array of the same structs as returned by the
2787 aria2.tellStatus() method. For the keys parameter, please refer
2788 to the aria2.tellStatus() method.
2789 aria2.tellWaiting([secret], offset, num[, keys])
2791 This method returns a list of waiting downloads, including
2792 paused ones. offset is an integer and specifies the offset from
2793 the download waiting at the front. num is an integer and speci‐
2794 fies the max. number of downloads to be returned. For the keys
2795 parameter, please refer to the aria2.tellStatus() method.
2796 If offset is a positive integer, this method returns downloads
2798 in the range of [offset, offset + num).
2799 offset can be a negative integer. offset == -1 points last down‐
2801 load in the waiting queue and offset == -2 points the download
2802 before the last download, and so on. Downloads in the response
2803 are in reversed order then.
2804 For example, imagine three downloads "A","B" and "C" are waiting
2806 in this order. aria2.tellWaiting(0, 1) returns ["A"].
2807 aria2.tellWaiting(1, 2) returns ["B", "C"]. aria2.tellWait‐
2808 ing(-1, 2) returns ["C", "B"].
2809 The response is an array of the same structs as returned by
2811 aria2.tellStatus() method.
2812 aria2.tellStopped([secret], offset, num[, keys])
2814 This method returns a list of stopped downloads. offset is an
2815 integer and specifies the offset from the least recently stopped
2816 download. num is an integer and specifies the max. number of
2817 downloads to be returned. For the keys parameter, please refer
2818 to the aria2.tellStatus() method.
2819 offset and num have the same semantics as described in the
2821 aria2.tellWaiting() method.
2822 The response is an array of the same structs as returned by the
2824 aria2.tellStatus() method.
2825 aria2.changePosition([secret], gid, pos, how)
2827 This method changes the position of the download denoted by gid
2828 in the queue. pos is an integer. how is a string. If how is
2829 POS_SET, it moves the download to a position relative to the be‐
2830 ginning of the queue. If how is POS_CUR, it moves the download
2831 to a position relative to the current position. If how is
2832 POS_END, it moves the download to a position relative to the end
2833 of the queue. If the destination position is less than 0 or be‐
2834 yond the end of the queue, it moves the download to the begin‐
2835 ning or the end of the queue respectively. The response is an
2836 integer denoting the resulting position.
2837 For example, if GID#2089b05ecca3d829 is currently in position 3,
2839 aria2.changePosition('2089b05ecca3d829', -1, 'POS_CUR') will
2840 change its position to 2. Additionally aria2.changePosi‐
2841 tion('2089b05ecca3d829', 0, 'POS_SET') will change its position
2842 to 0 (the beginning of the queue).
2843 The following examples move the download GID#2089b05ecca3d829 to
2845 the front of the queue.
2846 JSON-RPC Example
2848 >>> import urllib2, json
2850 >>> from pprint import pprint
2851 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2852 ... 'method':'aria2.changePosition',
2853 ... 'params':['2089b05ecca3d829', 0, 'POS_SET']})
2854 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2855 >>> pprint(json.loads(c.read()))
2856 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': 0}
2857 XML-RPC Example
2859 >>> import xmlrpclib
2861 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2862 >>> s.aria2.changePosition('2089b05ecca3d829', 0, 'POS_SET')
2863 0
2864 aria2.changeUri([secret], gid, fileIndex, delUris, addUris[, position])
2866 This method removes the URIs in delUris from and appends the
2867 URIs in addUris to download denoted by gid. delUris and addUris
2868 are lists of strings. A download can contain multiple files and
2869 URIs are attached to each file. fileIndex is used to select
2870 which file to remove/attach given URIs. fileIndex is 1-based.
2871 position is used to specify where URIs are inserted in the ex‐
2872 isting waiting URI list. position is 0-based. When position is
2873 omitted, URIs are appended to the back of the list. This method
2874 first executes the removal and then the addition. position is
2875 the position after URIs are removed, not the position when this
2876 method is called. When removing an URI, if the same URIs exist
2877 in download, only one of them is removed for each URI in
2878 delUris. In other words, if there are three URIs http://exam‐
2879 ple.org/aria2 and you want remove them all, you have to specify
2880 (at least) 3 http://example.org/aria2 in delUris. This method
2881 returns a list which contains two integers. The first integer is
2882 the number of URIs deleted. The second integer is the number of
2883 URIs added.
2884 The following examples add the URI http://example.org/file to
2886 the file whose index is 1 and belongs to the download
2887 GID#2089b05ecca3d829.
2888 JSON-RPC Example
2890 >>> import urllib2, json
2892 >>> from pprint import pprint
2893 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2894 ... 'method':'aria2.changeUri',
2895 ... 'params':['2089b05ecca3d829', 1, [],
2896 ['http://example.org/file']]})
2897 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2898 >>> pprint(json.loads(c.read()))
2899 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [0, 1]}
2900 XML-RPC Example
2902 >>> import xmlrpclib
2904 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2905 >>> s.aria2.changeUri('2089b05ecca3d829', 1, [],
2906 ['http://example.org/file'])
2907 [0, 1]
2908 aria2.getOption([secret], gid)
2910 This method returns options of the download denoted by gid. The
2911 response is a struct where keys are the names of options. The
2912 values are strings. Note that this method does not return op‐
2913 tions which have no default value and have not been set on the
2914 command-line, in configuration files or RPC methods.
2915 The following examples get options of the download
2917 GID#2089b05ecca3d829.
2918 JSON-RPC Example
2920 >>> import urllib2, json
2922 >>> from pprint import pprint
2923 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2924 ... 'method':'aria2.getOption',
2925 ... 'params':['2089b05ecca3d829']})
2926 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2927 >>> pprint(json.loads(c.read()))
2928 {u'id': u'qwer',
2929 u'jsonrpc': u'2.0',
2930 u'result': {u'allow-overwrite': u'false',
2931 u'allow-piece-length-change': u'false',
2932 u'always-resume': u'true',
2933 u'async-dns': u'true',
2934 ...
2935 XML-RPC Example
2937 >>> import xmlrpclib
2939 >>> from pprint import pprint
2940 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2941 >>> r = s.aria2.getOption('2089b05ecca3d829')
2942 >>> pprint(r)
2943 {'allow-overwrite': 'false',
2944 'allow-piece-length-change': 'false',
2945 'always-resume': 'true',
2946 'async-dns': 'true',
2947 ....
2948 aria2.changeOption([secret], gid, options)
2950 This method changes options of the download denoted by gid
2951 (string) dynamically. options is a struct. The options listed
2952 in Input File subsection are available, except for following op‐
2953 tions:
2954 • dry-run
2956 • metalink-base-uri
2958 • parameterized-uri
2960 • pause
2962 • piece-length
2964 • rpc-save-upload-metadata
2966 Except for the following options, changing the other options of
2968 active download makes it restart (restart itself is managed by
2969 aria2, and no user intervention is required):
2970 • bt-max-peers
2972 • bt-request-peer-speed-limit
2974 • bt-remove-unselected-file
2976 • force-save
2978 • max-download-limit
2980 • max-upload-limit
2982 This method returns OK for success.
2984 The following examples set the max-download-limit option to 20K
2986 for the download GID#2089b05ecca3d829.
2987 JSON-RPC Example
2989 >>> import urllib2, json
2991 >>> from pprint import pprint
2992 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2993 ... 'method':'aria2.changeOption',
2994 ... 'params':['2089b05ecca3d829',
2995 ... {'max-download-limit':'10K'}]})
2996 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2997 >>> pprint(json.loads(c.read()))
2998 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'}
2999 XML-RPC Example
3001 >>> import xmlrpclib
3003 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3004 >>> s.aria2.changeOption('2089b05ecca3d829', {'max-download-limit':'20K'})
3005 'OK'
3006 aria2.getGlobalOption([secret])
3008 This method returns the global options. The response is a
3009 struct. Its keys are the names of options. Values are strings.
3010 Note that this method does not return options which have no de‐
3011 fault value and have not been set on the command-line, in con‐
3012 figuration files or RPC methods. Because global options are used
3013 as a template for the options of newly added downloads, the re‐
3014 sponse contains keys returned by the aria2.getOption() method.
3015 aria2.changeGlobalOption([secret], options)
3017 This method changes global options dynamically. options is a
3018 struct. The following options are available:
3019 • bt-max-open-files
3021 • download-result
3023 • keep-unfinished-download-result
3025 • log
3027 • log-level
3029 • max-concurrent-downloads
3031 • max-download-result
3033 • max-overall-download-limit
3035 • max-overall-upload-limit
3037 • optimize-concurrent-downloads
3039 • save-cookies
3041 • save-session
3043 • server-stat-of
3045 In addition, options listed in the Input File subsection are
3047 available, except for following options: checksum, index-out,
3048 out, pause and select-file.
3049 With the log option, you can dynamically start logging or change
3051 log file. To stop logging, specify an empty string("") as the
3052 parameter value. Note that log file is always opened in append
3053 mode. This method returns OK for success.
3054 aria2.getGlobalStat([secret])
3056 This method returns global statistics such as the overall down‐
3057 load and upload speeds. The response is a struct and contains
3058 the following keys. Values are strings.
3059 downloadSpeed
3061 Overall download speed (byte/sec).
3062 uploadSpeed
3064 Overall upload speed(byte/sec).
3065 numActive
3067 The number of active downloads.
3068 numWaiting
3070 The number of waiting downloads.
3071 numStopped
3073 The number of stopped downloads in the current session.
3074 This value is capped by the --max-download-result option.
3075 numStoppedTotal
3077 The number of stopped downloads in the current session
3078 and not capped by the --max-download-result option.
3079 JSON-RPC Example
3081 >>> import urllib2, json
3083 >>> from pprint import pprint
3084 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3085 ... 'method':'aria2.getGlobalStat'})
3086 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3087 >>> pprint(json.loads(c.read()))
3088 {u'id': u'qwer',
3089 u'jsonrpc': u'2.0',
3090 u'result': {u'downloadSpeed': u'21846',
3091 u'numActive': u'2',
3092 u'numStopped': u'0',
3093 u'numWaiting': u'0',
3094 u'uploadSpeed': u'0'}}
3095 XML-RPC Example
3097 >>> import xmlrpclib
3099 >>> from pprint import pprint
3100 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3101 >>> r = s.aria2.getGlobalStat()
3102 >>> pprint(r)
3103 {'downloadSpeed': '23136',
3104 'numActive': '2',
3105 'numStopped': '0',
3106 'numWaiting': '0',
3107 'uploadSpeed': '0'}
3108 aria2.purgeDownloadResult([secret])
3110 This method purges completed/error/removed downloads to free
3111 memory. This method returns OK.
3112 aria2.removeDownloadResult([secret], gid)
3114 This method removes a completed/error/removed download denoted
3115 by gid from memory. This method returns OK for success.
3116 The following examples remove the download result of the down‐
3118 load GID#2089b05ecca3d829.
3119 JSON-RPC Example
3121 >>> import urllib2, json
3123 >>> from pprint import pprint
3124 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3125 ... 'method':'aria2.removeDownloadResult',
3126 ... 'params':['2089b05ecca3d829']})
3127 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3128 >>> pprint(json.loads(c.read()))
3129 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'}
3130 XML-RPC Example
3132 >>> import xmlrpclib
3134 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3135 >>> s.aria2.removeDownloadResult('2089b05ecca3d829')
3136 'OK'
3137 aria2.getVersion([secret])
3139 This method returns the version of aria2 and the list of enabled
3140 features. The response is a struct and contains following keys.
3141 version
3143 Version number of aria2 as a string.
3144 enabledFeatures
3146 List of enabled features. Each feature is given as a
3147 string.
3148 JSON-RPC Example
3150 >>> import urllib2, json
3152 >>> from pprint import pprint
3153 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3154 ... 'method':'aria2.getVersion'})
3155 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3156 >>> pprint(json.loads(c.read()))
3157 {u'id': u'qwer',
3158 u'jsonrpc': u'2.0',
3159 u'result': {u'enabledFeatures': [u'Async DNS',
3160 u'BitTorrent',
3161 u'Firefox3 Cookie',
3162 u'GZip',
3163 u'HTTPS',
3164 u'Message Digest',
3165 u'Metalink',
3166 u'XML-RPC'],
3167 u'version': u'1.11.0'}}
3168 XML-RPC Example
3170 >>> import xmlrpclib
3172 >>> from pprint import pprint
3173 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3174 >>> r = s.aria2.getVersion()
3175 >>> pprint(r)
3176 {'enabledFeatures': ['Async DNS',
3177 'BitTorrent',
3178 'Firefox3 Cookie',
3179 'GZip',
3180 'HTTPS',
3181 'Message Digest',
3182 'Metalink',
3183 'XML-RPC'],
3184 'version': '1.11.0'}
3185 aria2.getSessionInfo([secret])
3187 This method returns session information. The response is a
3188 struct and contains following key.
3189 sessionId
3191 Session ID, which is generated each time when aria2 is
3192 invoked.
3193 JSON-RPC Example
3195 >>> import urllib2, json
3197 >>> from pprint import pprint
3198 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3199 ... 'method':'aria2.getSessionInfo'})
3200 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3201 >>> pprint(json.loads(c.read()))
3202 {u'id': u'qwer',
3203 u'jsonrpc': u'2.0',
3204 u'result': {u'sessionId': u'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}}
3205 XML-RPC Example
3207 >>> import xmlrpclib
3209 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3210 >>> s.aria2.getSessionInfo()
3211 {'sessionId': 'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}
3212 aria2.shutdown([secret])
3214 This method shuts down aria2. This method returns OK.
3215 aria2.forceShutdown([secret])
3217 This method shuts down aria2(). This method behaves like
3218 :func:'aria2.shutdown` without performing any actions which take
3219 time, such as contacting BitTorrent trackers to unregister down‐
3220 loads first. This method returns OK.
3221 aria2.saveSession([secret])
3223 This method saves the current session to a file specified by the
3224 --save-session option. This method returns OK if it succeeds.
3225 system.multicall(methods)
3227 This methods encapsulates multiple method calls in a single re‐
3228 quest. methods is an array of structs. The structs contain two
3229 keys: methodName and params. methodName is the method name to
3230 call and params is array containing parameters to the method
3231 call. This method returns an array of responses. The elements
3232 will be either a one-item array containing the return value of
3233 the method call or a struct of fault element if an encapsulated
3234 method call fails.
3235 In the following examples, we add 2 downloads. The first one is
3237 http://example.org/file and the second one is file.torrent.
3238 JSON-RPC Example
3240 >>> import urllib2, json, base64
3242 >>> from pprint import pprint
3243 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3244 ... 'method':'system.multicall',
3245 ... 'params':[[{'methodName':'aria2.addUri',
3246 ... 'params':[['http://example.org']]},
3247 ... {'methodName':'aria2.addTorrent',
3248 ... 'params':[base64.b64encode(open('file.torrent').read())]}]]})
3249 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3250 >>> pprint(json.loads(c.read()))
3251 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [[u'2089b05ecca3d829'], [u'd2703803b52216d1']]}
3252 JSON-RPC additionally supports Batch requests as described in
3254 the JSON-RPC 2.0 Specification:
3255 >>> jsonreq = json.dumps([{'jsonrpc':'2.0', 'id':'qwer',
3257 ... 'method':'aria2.addUri',
3258 ... 'params':[['http://example.org']]},
3259 ... {'jsonrpc':'2.0', 'id':'asdf',
3260 ... 'method':'aria2.addTorrent',
3261 ... 'params':[base64.b64encode(open('file.torrent').read())]}])
3262 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3263 >>> pprint(json.loads(c.read()))
3264 [{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'2089b05ecca3d829'},
3265 {u'id': u'asdf', u'jsonrpc': u'2.0', u'result': u'd2703803b52216d1'}]
3266 XML-RPC Example
3268 >>> import xmlrpclib
3270 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3271 >>> mc = xmlrpclib.MultiCall(s)
3272 >>> mc.aria2.addUri(['http://example.org/file'])
3273 >>> mc.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent', mode='rb').read()))
3274 >>> r = mc()
3275 >>> tuple(r)
3276 ('2089b05ecca3d829', 'd2703803b52216d1')
3277 system.listMethods()
3279 This method returns all the available RPC methods in an array of
3280 string. Unlike other methods, this method does not require se‐
3281 cret token. This is safe because this method just returns the
3282 available method names.
3283 JSON-RPC Example
3285 >>> import urllib2, json
3287 >>> from pprint import pprint
3288 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3289 ... 'method':'system.listMethods'})
3290 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3291 >>> pprint(json.loads(c.read()))
3292 {u'id': u'qwer',
3293 u'jsonrpc': u'2.0',
3294 u'result': [u'aria2.addUri',
3295 u'aria2.addTorrent',
3296 ...
3297 XML-RPC Example
3299 >>> import xmlrpclib
3301 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3302 >>> s.system.listMethods()
3303 ['aria2.addUri', 'aria2.addTorrent', ...
3304 system.listNotifications()
3306 This method returns all the available RPC notifications in an
3307 array of string. Unlike other methods, this method does not re‐
3308 quire secret token. This is safe because this method just re‐
3309 turns the available notifications names.
3310 JSON-RPC Example
3312 >>> import urllib2, json
3314 >>> from pprint import pprint
3315 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3316 ... 'method':'system.listNotifications'})
3317 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3318 >>> pprint(json.loads(c.read()))
3319 {u'id': u'qwer',
3320 u'jsonrpc': u'2.0',
3321 u'result': [u'aria2.onDownloadStart',
3322 u'aria2.onDownloadPause',
3323 ...
3324 XML-RPC Example
3326 >>> import xmlrpclib
3328 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3329 >>> s.system.listNotifications()
3330 ['aria2.onDownloadStart', 'aria2.onDownloadPause', ...
3331 Error Handling
3333 Over JSON-RPC, aria2 returns a JSON object which contains an error code
3334 in code and the error message in message.
3335 Over XML-RPC, aria2 returns faultCode=1 and the error message in fault‐
3337 String.
3338 Options
3340 The same options as for --input-file are available. See the Input File
3341 subsection for a complete list of options.
3342 In the option struct, the name element is the option name (without the
3344 preceding --) and the value element is the argument as a string.
3345 JSON-RPC Example
3347 {'split':'1', 'http-proxy':'http://proxy/'}
3348 XML-RPC Example
3350 <struct>
3351 <member>
3352 <name>split</name>
3353 <value><string>1</string></value>
3354 </member>
3355 <member>
3356 <name>http-proxy</name>
3357 <value><string>http://proxy/</string></value>
3358 </member>
3359 </struct>
3360 The header and index-out options are allowed multiple times on the com‐
3362 mand-line. Since the name should be unique in a struct (many XML-RPC
3363 library implementations use a hash or dict for struct), a single string
3364 is not enough. To overcome this limitation, you may use an array as the
3365 value as well as a string.
3366 JSON-RPC Example
3368 {'header':['Accept-Language: ja', 'Accept-Charset: utf-8']}
3369 XML-RPC Example
3371 <struct>
3372 <member>
3373 <name>header</name>
3374 <value>
3375 <array>
3376 <data>
3377 <value><string>Accept-Language: ja</string></value>
3378 <value><string>Accept-Charset: utf-8</string></value>
3379 </data>
3380 </array>
3381 </value>
3382 </member>
3383 </struct>
3384 The following example adds a download with two options: dir and header.
3386 The header option requires two values, so it uses a list:
3387 >>> import xmlrpclib
3389 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3390 >>> opts = dict(dir='/tmp',
3391 ... header=['Accept-Language: ja',
3392 ... 'Accept-Charset: utf-8'])
3393 >>> s.aria2.addUri(['http://example.org/file'], opts)
3394 '1'
3395 JSON-RPC using HTTP GET
3397 The JSON-RPC interface also supports requests via HTTP GET. The encod‐
3398 ing scheme in GET parameters is based on JSON-RPC over HTTP Specifica‐
3399 tion [2008-1-15(RC1)]. The encoding of GET parameters are follows:
3400 /jsonrpc?method=METHOD_NAME&id=ID¶ms=BASE64_ENCODED_PARAMS
3402 The method and id are always treated as JSON string and their encoding
3404 must be UTF-8.
3405 For example, The encoded string of aria2.tellStatus('2089b05ecca3d829')
3407 with id='foo' looks like this:
3408 /jsonrpc?method=aria2.tellStatus&id=foo¶ms=WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D
3410 The params parameter is Base64-encoded JSON array which usually appears
3412 in params attribute in JSON-RPC request object. In the above example,
3413 the params is ["2089b05ecca3d829"], therefore:
3414 ["2089b05ecca3d829"] --(Base64)--> WyIyMDg5YjA1ZWNjYTNkODI5Il0=
3416 --(Percent Encode)--> WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D
3417 The JSON-RPC interface also supports JSONP. You can specify the call‐
3419 back function in the jsoncallback parameter:
3420 /jsonrpc?method=aria2.tellStatus&id=foo¶ms=WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D&jsoncallback=cb
3422 For Batch requests, the method and id parameters must not be specified.
3424 The whole request must be specified in the params parameter. For exam‐
3425 ple, a Batch request:
3426 [{'jsonrpc':'2.0', 'id':'qwer', 'method':'aria2.getVersion'},
3428 {'jsonrpc':'2.0', 'id':'asdf', 'method':'aria2.tellActive'}]
3429 must be encoded like this:
3431 /jsonrpc?params=W3sianNvbnJwYyI6ICIyLjAiLCAiaWQiOiAicXdlciIsICJtZXRob2QiOiAiYXJpYTIuZ2V0VmVyc2lvbiJ9LCB7Impzb25ycGMiOiAiMi4wIiwgImlkIjogImFzZGYiLCAibWV0aG9kIjogImFyaWEyLnRlbGxBY3RpdmUifV0%3D
3433 JSON-RPC over WebSocket
3435 JSON-RPC over WebSocket uses same method signatures and response format
3436 as JSON-RPC over HTTP. The supported WebSocket version is 13 which is
3437 detailed in RFC 6455.
3438 To send a RPC request to the RPC server, send a serialized JSON string
3440 in a Text frame. The response from the RPC server is delivered also in
3441 a Text frame.
3442 Notifications
3444 The RPC server might send notifications to the client. Notifications is
3445 unidirectional, therefore the client which receives the notification
3446 must not respond to it. The method signature of a notification is much
3447 like a normal method request but lacks the id key. The value of the
3448 params key is the data which this notification carries. The format of
3449 the value varies depending on the notification method. Following noti‐
3450 fication methods are defined.
3451 aria2.onDownloadStart(event)
3453 This notification will be sent when a download is started. The
3454 event is of type struct and it contains following keys. The
3455 value type is string.
3456 gid GID of the download.
3458 aria2.onDownloadPause(event)
3460 This notification will be sent when a download is paused. The
3461 event is the same struct as the event argument of
3462 aria2.onDownloadStart() method.
3463 aria2.onDownloadStop(event)
3465 This notification will be sent when a download is stopped by the
3466 user. The event is the same struct as the event argument of
3467 aria2.onDownloadStart() method.
3468 aria2.onDownloadComplete(event)
3470 This notification will be sent when a download is complete. For
3471 BitTorrent downloads, this notification is sent when the down‐
3472 load is complete and seeding is over. The event is the same
3473 struct of the event argument of aria2.onDownloadStart() method.
3474 aria2.onDownloadError(event)
3476 This notification will be sent when a download is stopped due to
3477 an error. The event is the same struct as the event argument of
3478 aria2.onDownloadStart() method.
3479 aria2.onBtDownloadComplete(event)
3481 This notification will be sent when a torrent download is com‐
3482 plete but seeding is still going on. The event is the same
3483 struct as the event argument of aria2.onDownloadStart() method.
3484 Sample XML-RPC Client Code
3486 The following Ruby script adds http://localhost/aria2.tar.bz2 to aria2c
3487 (running on localhost) with option --dir=/downloads and prints the RPC
3488 response:
3489 #!/usr/bin/env ruby
3491 require 'xmlrpc/client'
3493 require 'pp'
3494 client=XMLRPC::Client.new2("http://localhost:6800/rpc")
3496 options={ "dir" => "/downloads" }
3498 result=client.call("aria2.addUri", [ "http://localhost/aria2.tar.bz2" ], options)
3499 pp result
3501 If you are a Python lover, you can use xmlrpclib (Python3 uses xml‐
3503 rpc.client instead) to interact with aria2:
3504 import xmlrpclib
3506 from pprint import pprint
3507 s = xmlrpclib.ServerProxy("http://localhost:6800/rpc")
3509 r = s.aria2.addUri(["http://localhost/aria2.tar.bz2"], {"dir":"/downloads"})
3510 pprint(r)
3511
3513 Console Readout
3514 While downloading files, aria2 prints a readout to the console to show
3515 the progress of the downloads. The console readout looks like this:
3516 [#2089b0 400.0KiB/33.2MiB(1%) CN:1 DL:115.7KiB ETA:4m51s]
3518 This section describes what these numbers and strings mean.
3520 #NNNNNN
3522 The first 6 characters of the GID as a hex string. The GID is an
3523 unique ID for each download, internal to aria2. The GID is par‐
3524 ticularly useful when interacting with aria2 using the RPC in‐
3525 terface.
3526 X/Y(Z%)
3528 Completed length, the total file length and its progress. If
3529 --select-file is used, this is the sum of selected files.
3530 SEED Share ratio when the aria2 is seeding a finished torrent.
3532 CN The number of connections aria2 has established.
3534 SD The number of seeders aria2 is connected to.
3536 DL Download speed (bytes per second).
3538 UL Upload speed (bytes per second) and the number of uploaded
3540 bytes.
3541 ETA Expected time to finish the download.
3543 When more than one download is in progress, some of the information de‐
3545 scribed above will be omitted in order to show information for several
3546 downloads. And the overall download and upload speeds are shown at the
3547 beginning of the line.
3548 When aria2 is allocating file space or validating checksums, it addi‐
3550 tionally prints the progress of these operations:
3551 FileAlloc
3553 GID, already allocated length and total length in bytes.
3554 Checksum
3556 GID, already validated length and total length in bytes.
3557
3559 HTTP/FTP Segmented Downloads
3560 Download a file
3561 $ aria2c "http://host/file.zip"
3562 NOTE:
3564 To stop a download, press Ctrl-C. You can resume the transfer by
3565 running aria2c with the same argument in the same directory. You can
3566 change URIs as long as they are pointing to the same file.
3567 Download a file from two different HTTP servers
3569 $ aria2c "http://host/file.zip" "http://mirror/file.zip"
3570 Download a file from one host using multiple connections
3572 $ aria2c -x2 -k1M "http://host/file.zip"
3573 NOTE:
3575 The -x option specified the number of allowed connections, while the
3576 -k option specified the size of chunks.
3577 Download a file from HTTP and FTP servers at the same time
3579 $ aria2c "http://host1/file.zip" "ftp://host2/file.zip"
3580 Download files listed in a text file concurrently
3582 $ aria2c -ifiles.txt -j2
3583 NOTE:
3585 -j option specifies the number of parallel downloads.
3586 Using a proxy
3588 For HTTP:
3589 $ aria2c --http-proxy="http://proxy:8080" "http://host/file"
3591 $ aria2c --http-proxy="http://proxy:8080" --no-proxy="localhost,127.0.0.1,192.168.0.0/16" "http://host/file"
3593 For FTP:
3595 $ aria2c --ftp-proxy="http://proxy:8080" "ftp://host/file"
3597 NOTE:
3599 See --http-proxy, --https-proxy, --ftp-proxy, --all-proxy and
3600 --no-proxy for details. You can specify proxy in the environment
3601 variables. See ENVIRONMENT section.
3602 Using a Proxy with authorization
3604 $ aria2c --http-proxy="http://username:password@proxy:8080" "http://host/file"
3605 $ aria2c --http-proxy="http://proxy:8080" --http-proxy-user="username" --http-proxy-passwd="password" "http://host/file"
3607 Metalink Download
3609 Download files with remote Metalink
3610 $ aria2c --follow-metalink=mem "http://host/file.metalink"
3611 Download using a local metalink file
3613 $ aria2c -p --lowest-speed-limit=4000 file.metalink
3614 NOTE:
3616 To stop a download, press Ctrl-C. You can resume the transfer by
3617 running aria2c with the same argument in the same directory.
3618 Download several local metalink files
3620 $ aria2c -j2 file1.metalink file2.metalink
3621 Download only selected files
3623 $ aria2c --select-file=1-4,8 file.metalink
3624 NOTE:
3626 The index is printed to the console using -S option.
3627 Download a file using a local metalink file with user preference
3629 $ aria2c --metalink-location=jp,us --metalink-version=1.1 --metalink-language=en-US file.metalink
3630 BitTorrent Download
3632 Download files using a remote BitTorrent file
3633 $ aria2c --follow-torrent=mem "http://host/file.torrent"
3634 Download using a local torrent file
3636 $ aria2c --max-upload-limit=40K file.torrent
3637 NOTE:
3639 --max-upload-limit specifies the max of upload rate.
3640 NOTE:
3642 To stop a download, press Ctrl-C. You can resume the transfer later
3643 by running aria2c with the same argument in the same directory.
3644 Download using BitTorrent Magnet URI
3646 $ aria2c "magnet:?xt=urn:btih:248D0A1CD08284299DE78D5C1ED359BB46717D8C&dn=aria2"
3647 NOTE:
3649 Don't forget to quote BitTorrent Magnet URIs which include & charac‐
3650 ters with single(') or double(") quotes when specifying URIs on the
3651 command-line.
3652 Download 2 torrents
3654 $ aria2c -j2 file1.torrent file2.torrent
3655 Download a file via torrent and HTTP/FTP server in parallel
3657 $ aria2c -Ttest.torrent "http://host1/file" "ftp://host2/file"
3658 Only download specific files (usually called selected download )
3660 $ aria2c --select-file=1-4,8 file.torrent
3661 NOTE:
3663 The index is printed to the console using -S option.
3664 Download a .torrent file, but do not download the torrent
3666 $ aria2c --follow-torrent=false "http://host/file.torrent"
3667 Specify the output file name
3669 To specify the output file name for BitTorrent downloads, you need to
3670 know the index of file in the torrent (see --show-files). For example,
3671 the output looks like this:
3672 idx|path/length
3674 ===+======================
3675 1|dist/base-2.6.18.iso
3676 |99.9MiB
3677 ---+----------------------
3678 2|dist/driver-2.6.18.iso
3679 |169.0MiB
3680 ---+----------------------
3681 To save 'dist/base-2.6.18.iso' in '/tmp/mydir/base.iso' and
3683 'dist/driver-2.6.18.iso' in '/tmp/dir/driver.iso', use the following
3684 command:
3685 $ aria2c --dir=/tmp --index-out=1=mydir/base.iso --index-out=2=dir/driver.iso file.torrent
3687 Change the listening ports for incoming peer connections
3689 $ aria2c --listen-port=7000-7001,8000 file.torrent
3690 NOTE:
3692 Since aria2 doesn't configure firewalls or routers for port forward‐
3693 ing, it's up to you to do so manually.
3694 Specify conditions to stop seeding after torrent downloads finish
3696 $ aria2c --seed-time=120 --seed-ratio=1.0 file.torrent
3697 NOTE:
3699 In the above example, the program stops seeding after 120 minutes
3700 since download completed or seed ratio reaches 1.0.
3701 Throttle upload speed
3703 $ aria2c --max-upload-limit=100K file.torrent
3704 Enable IPv4 DHT
3706 $ aria2c --enable-dht --dht-listen-port=6881 file.torrent
3707 NOTE:
3709 DHT uses UDP. Since aria2 doesn't configure firewalls or routers for
3710 port forwarding, it's up to you to do it manually.
3711 Enable IPv6 DHT
3713 $ aria2c --enable-dht6 --dht-listen-port=6881 --dht-listen-addr6=YOUR_GLOBAL_UNICAST_IPV6_ADDR
3714 NOTE:
3716 aria2 uses the same ports as IPv4 for IPv6.
3717 Add and remove tracker URIs
3719 Ignore all tracker announce URIs defined in file.torrent and use
3720 http://tracker1/announce and http://tracker2/announce instead:
3721 $ aria2c --bt-exclude-tracker="*" --bt-tracker="http://tracker1/announce,http://tracker2/announce" file.torrent
3723 More advanced HTTP features
3725 Load cookies
3726 $ aria2c --load-cookies=cookies.txt "http://host/file.zip"
3727 NOTE:
3729 You can use Firefox/Mozilla/Chromium's cookie files without modifi‐
3730 cation.
3731 Resume download started by web browsers or other programs
3733 $ aria2c -c -s2 "http://host/partiallydownloadedfile.zip"
3734 NOTE:
3736 This will only work when the initial download was not multi-seg‐
3737 mented.
3738 Client certificate authorization for SSL/TLS
3740 Specify a PKCS12 file as follows:
3741 $ aria2c --certificate=/path/to/mycert.p12
3743 NOTE:
3745 The file specified in --certificate must be contain one PKCS12 en‐
3746 coded certificate and key. The password must be blank.
3747 Alternatively, if PEM files are supported, use a command like the fol‐
3749 lowing:
3750 $ aria2c --certificate=/path/to/mycert.pem --private-key=/path/to/mykey.pem https://host/file
3752 NOTE:
3754 The file specified in --private-key must be decrypted. The behavior
3755 when encrypted one is given is undefined.
3756 Verify SSL/TLS servers using given CA certificates
3758 $ aria2c --ca-certificate=/path/to/ca-certificates.crt --check-certificate https://host/file
3759 NOTE:
3761 This option is only available when aria2 was compiled against GnuTLS
3762 or OpenSSL. WinTLS and AppleTLS will always use the system certifi‐
3763 cate store. Instead of `--ca-certificate install the certificate in
3764 that store.
3765 RPC
3767 Encrypt RPC traffic with SSL/TLS
3768 Specify a server PKC12 file:
3769 $ aria2c --enable-rpc --rpc-certificate=/path/to/server.p12 --rpc-secure
3771 NOTE:
3773 The file specified in --rpc-certificate must be contain one PKCS12
3774 encoded certificate and key. The password must be blank.
3775 Alternatively, when PEM files are supported (GnuTLS and OpenSSL), spec‐
3777 ify the server certificate file and private key file as follows:
3778 $ aria2c --enable-rpc --rpc-certificate=/path/to/server.crt --rpc-private-key=/path/to/server.key --rpc-secure
3780 And more advanced features
3782 Throttle the download speed
3783 Per-download:
3784 $ aria2c --max-download-limit=100K file.metalink
3786 Overall:
3788 $ aria2c --max-overall-download-limit=100K file.metalink
3790 Repair a damaged download
3792 $ aria2c -V file.metalink
3793 NOTE:
3795 Repairing damaged downloads can be done efficiently when used with
3796 BitTorrent or Metalink with chunk checksums.
3797 Drop connections if download speed is lower than a specified limit
3799 $ aria2c --lowest-speed-limit=10K file.metalink
3800 Parameterized URI support
3802 You can specify set of parts:
3803 $ aria2c -P "http://{host1,host2,host3}/file.iso"
3805 You can specify numeric sequence:
3807 $ aria2c -Z -P "http://host/image[000-100].png"
3809 NOTE:
3811 The -Z option is required if the URIs don't point to the same file,
3812 such as in the above example.
3813 You can specify step counter:
3815 $ aria2c -Z -P "http://host/image[A-Z:2].png"
3817 Verifying checksums
3819 $ aria2c --checksum=sha-1=0192ba11326fe2298c8cb4de616f4d4140213837 http://example.org/file
3820 Parallel downloads of an arbitrary number of URIs, metalink, torrent
3822 $ aria2c -j3 -Z "http://host/file1" file2.torrent file3.metalink
3823 BitTorrent Encryption
3825 Encrypt the whole payload using ARC4 (obfuscation):
3826 $ aria2c --bt-min-crypto-level=arc4 --bt-require-crypto=true file.torrent
3828
3830 Project Web Site: https://aria2.github.io/
3831 Metalink Homepage: http://www.metalinker.org/
3833 The Metalink Download Description Format: RFC 5854
3835
3837 Copyright (C) 2006, 2015 Tatsuhiro Tsujikawa
3838 This program is free software; you can redistribute it and/or modify it
3840 under the terms of the GNU General Public License as published by the
3841 Free Software Foundation; either version 2 of the License, or (at your
3842 option) any later version.
3843 This program is distributed in the hope that it will be useful, but
3845 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
3846 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
3847 Public License for more details.
3848 You should have received a copy of the GNU General Public License along
3850 with this program; if not, write to the Free Software Foundation, Inc.,
3851 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
3852 In addition, as a special exception, the copyright holders give permis‐
3854 sion to link the code of portions of this program with the OpenSSL li‐
3855 brary under certain conditions as described in each individual source
3856 file, and distribute linked combinations including the two. You must
3857 obey the GNU General Public License in all respects for all of the code
3858 used other than OpenSSL. If you modify file(s) with this exception,
3859 you may extend this exception to your version of the file(s), but you
3860 are not obligated to do so. If you do not wish to do so, delete this
3861 exception statement from your version. If you delete this exception
3862 statement from all source files in the program, then also delete it
3863 here.
38641.36.0 Aug 21, 2021 ARIA2C(1)