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
24 options 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
69 entire file. This option has effect only in BitTorrent, Met‐
70 alink 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
81 option 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
101 affects 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
113 mypass.
114 Another example: if you specified on the command-line
116 --http-proxy="http://user:pass@proxy"
117 --http-proxy-user="myname" --http-proxy-passwd="mypass", then
118 you'd get HTTP proxy http://proxy with user myname and pass‐
119 word mypass.
120 One more example: if you specified in command-line
122 --http-proxy-user="myname" --http-proxy-passwd="mypass"
123 --http-proxy="http://user:pass@proxy", then you'd get HTTP
124 proxy http://proxy with user user and password pass.
125 --all-proxy-passwd=<PASSWD>
127 Set password for --all-proxy option.
128 --all-proxy-user=<USER>
130 Set user for --all-proxy option.
131 --checksum=<TYPE>=<DIGEST>
133 Set checksum. TYPE is hash type. The supported hash type is
134 listed in Hash Algorithms in aria2c -v. DIGEST is hex digest.
135 For example, setting sha-1 digest looks like this:
136 sha-1=0192ba11326fe2298c8cb4de616f4d4140213838 This option
137 applies only to HTTP(S)/FTP downloads.
138 --connect-timeout=<SEC>
140 Set the connect timeout in seconds to establish connection to
141 HTTP/FTP/proxy server. After the connection is established, this
142 option makes no effect and --timeout option is used instead.
143 Default: 60
144 --dry-run [true|false]
146 If true is given, aria2 just checks whether the remote file is
147 available and doesn't download data. This option has effect on
148 HTTP/FTP download. BitTorrent downloads are canceled if true is
149 specified. Default: false
150 --lowest-speed-limit=<SPEED>
152 Close connection if download speed is lower than or equal to
153 this value(bytes per sec). 0 means aria2 does not have a lowest
154 speed limit. You can append K or M (1K = 1024, 1M = 1024K).
155 This option does not affect BitTorrent downloads. Default: 0
156 -x, --max-connection-per-server=<NUM>
158 The maximum number of connections to one server for each down‐
159 load. Default: 1
160 --max-file-not-found=<NUM>
162 If aria2 receives "file not found" status from the remote
163 HTTP/FTP servers NUM times without getting a single byte, then
164 force the download to fail. Specify 0 to disable this option.
165 This options is effective only when using HTTP/FTP servers. The
166 number of retry attempt is counted toward --max-tries, so it
167 should be configured too.
168 Default: 0
170 -m, --max-tries=<N>
172 Set number of tries. 0 means unlimited. See also --retry-wait.
173 Default: 5
174 -k, --min-split-size=<SIZE>
176 aria2 does not split less than 2*SIZE byte range. For example,
177 let's consider downloading 20MiB file. If SIZE is 10M, aria2 can
178 split file into 2 range [0-10MiB) and [10MiB-20MiB) and download
179 it using 2 sources(if --split >= 2, of course). If SIZE is 15M,
180 since 2*15M > 20MiB, aria2 does not split file and download it
181 using 1 source. You can append K or M (1K = 1024, 1M = 1024K).
182 Possible Values: 1M -1024M Default: 20M
183 --netrc-path=<FILE>
185 Specify the path to the netrc file. Default: $(HOME)/.netrc
186 NOTE:
188 Permission of the .netrc file must be 600. Otherwise, the
189 file will be ignored.
190 -n, --no-netrc [true|false]
192 Disables netrc support. netrc support is enabled by default.
193 NOTE:
195 netrc file is only read at the startup if --no-netrc is
196 false. So if --no-netrc is true at the startup, no netrc is
197 available throughout the session. You cannot get netrc
198 enabled even if you send --no-netrc=false using
199 aria2.changeGlobalOption().
200 --no-proxy=<DOMAINS>
202 Specify a comma separated list of host names, domains and net‐
203 work addresses with or without a subnet mask where no proxy
204 should be used.
205 NOTE:
207 For network addresses with a subnet mask, both IPv4 and IPv6
208 addresses work. The current implementation does not resolve
209 the host name in an URI to compare network addresses speci‐
210 fied in --no-proxy. So it is only effective if URI has
211 numeric IP addresses.
212 -o, --out=<FILE>
214 The file name of the downloaded file. It is always relative to
215 the directory given in --dir option. When the
216 --force-sequential option is used, this option is ignored.
217 NOTE:
219 You cannot specify a file name for Metalink or BitTorrent
220 downloads. The file name specified here is only used when
221 the URIs fed to aria2 are given on the command line directly,
222 but not when using --input-file, --force-sequential option.
223 Example:
225 $ aria2c -o myfile.zip "http://mirror1/file.zip" "http://mirror2/file.zip"
227 --proxy-method=<METHOD>
229 Set the method to use in proxy request. METHOD is either get or
230 tunnel. HTTPS downloads always use tunnel regardless of this
231 option. Default: get
232 -R, --remote-time [true|false]
234 Retrieve timestamp of the remote file from the remote HTTP/FTP
235 server and if it is available, apply it to the local file.
236 Default: false
237 --reuse-uri [true|false]
239 Reuse already used URIs if no unused URIs are left. Default:
240 true
241 --retry-wait=<SEC>
243 Set the seconds to wait between retries. When SEC > 0, aria2
244 will retry downloads when the HTTP server returns a 503
245 response. Default: 0
246 --server-stat-of=<FILE>
248 Specify the file name to which performance profile of the
249 servers is saved. You can load saved data using --server-stat-if
250 option. See Server Performance Profile subsection below for file
251 format.
252 --server-stat-if=<FILE>
254 Specify the file name to load performance profile of the
255 servers. The loaded data will be used in some URI selector such
256 as feedback. See also --uri-selector option. See Server Perfor‐
257 mance Profile subsection below for file format.
258 --server-stat-timeout=<SEC>
260 Specifies timeout in seconds to invalidate performance profile
261 of the servers since the last contact to them. Default: 86400
262 (24hours)
263 -s, --split=<N>
265 Download a file using N connections. If more than N URIs are
266 given, first N URIs are used and remaining URIs are used for
267 backup. If less than N URIs are given, those URIs are used more
268 than once so that N connections total are made simultaneously.
269 The number of connections to the same host is restricted by the
270 --max-connection-per-server option. See also the
271 --min-split-size option. Default: 5
272 NOTE:
274 Some Metalinks regulate the number of servers to connect.
275 aria2 strictly respects them. This means that if Metalink
276 defines the maxconnections attribute lower than N, then aria2
277 uses the value of this lower value instead of N.
278 --stream-piece-selector=<SELECTOR>
280 Specify piece selection algorithm used in HTTP/FTP download.
281 Piece means fixed length segment which is downloaded in parallel
282 in segmented download. If default is given, aria2 selects piece
283 so that it reduces the number of establishing connection. This
284 is reasonable default behavior because establishing connection
285 is an expensive operation. If inorder is given, aria2 selects
286 piece which has minimum index. Index=0 means first of the file.
287 This will be useful to view movie while downloading it.
288 --enable-http-pipelining option may be useful to reduce re-con‐
289 nection overhead. Please note that aria2 honors
290 --min-split-size option, so it will be necessary to specify a
291 reasonable value to --min-split-size option. If random is
292 given, aria2 selects piece randomly. Like inorder,
293 --min-split-size option is honored. If geom is given, at the
294 beginning aria2 selects piece which has minimum index like
295 inorder, but it exponentially increasingly keeps space from pre‐
296 viously selected piece. This will reduce the number of estab‐
297 lishing connection and at the same time it will download the
298 beginning part of the file first. This will be useful to view
299 movie while downloading it. Default: default
300 -t, --timeout=<SEC>
302 Set timeout in seconds. Default: 60
303 --uri-selector=<SELECTOR>
305 Specify URI selection algorithm. The possible values are
306 inorder, feedback and adaptive. If inorder is given, URI is
307 tried in the order appeared in the URI list. If feedback is
308 given, aria2 uses download speed observed in the previous down‐
309 loads and choose fastest server in the URI list. This also
310 effectively skips dead mirrors. The observed download speed is a
311 part of performance profile of servers mentioned in
312 --server-stat-of and --server-stat-if options. If adaptive is
313 given, selects one of the best mirrors for the first and
314 reserved connections. For supplementary ones, it returns mir‐
315 rors which has not been tested yet, and if each of them has
316 already been tested, returns mirrors which has to be tested
317 again. Otherwise, it doesn't select anymore mirrors. Like feed‐
318 back, it uses a performance profile of servers. Default: feed‐
319 back
320 HTTP Specific Options
322 --ca-certificate=<FILE>
323 Use the certificate authorities in FILE to verify the peers.
324 The certificate file must be in PEM format and can contain mul‐
325 tiple CA certificates. Use --check-certificate option to enable
326 verification.
327 NOTE:
329 If you build with OpenSSL or the recent version of GnuTLS
330 which has gnutls_certificate_set_x509_system_trust() function
331 and the library is properly configured to locate the sys‐
332 tem-wide CA certificates store, aria2 will automatically load
333 those certificates at the startup.
334 NOTE:
336 WinTLS and AppleTLS do not support this option. Instead you
337 will have to import the certificate into the OS trust store.
338 --certificate=<FILE>
340 Use the client certificate in FILE. The certificate must be
341 either in PKCS12 (.p12, .pfx) or in PEM format.
342 PKCS12 files must contain the certificate, a key and optionally
344 a chain of additional certificates. Only PKCS12 files with a
345 blank import password can be opened!
346 When using PEM, you have to specify the private key via
348 --private-key as well.
349 NOTE:
351 WinTLS does not support PEM files at the moment. Users have
352 to use PKCS12 files.
353 NOTE:
355 AppleTLS users should use the KeyChain Access utility to
356 import the client certificate and get the SHA-1 fingerprint
357 from the Information dialog corresponding to that certifi‐
358 cate. To start aria2c use --certificate=<SHA-1>. Alterna‐
359 tively PKCS12 files are also supported. PEM files, however,
360 are not supported.
361 --check-certificate [true|false]
363 Verify the peer using certificates specified in --ca-certificate
364 option. Default: true
365 --http-accept-gzip [true|false]
367 Send Accept: deflate, gzip request header and inflate response
368 if remote server responds with Content-Encoding: gzip or Con‐
369 tent-Encoding: deflate. Default: false
370 NOTE:
372 Some server responds with Content-Encoding: gzip for files
373 which itself is gzipped file. aria2 inflates them anyway
374 because of the response header.
375 --http-auth-challenge [true|false]
377 Send HTTP authorization header only when it is requested by the
378 server. If false is set, then authorization header is always
379 sent to the server. There is an exception: if user name and
380 password are embedded in URI, authorization header is always
381 sent to the server regardless of this option. Default: false
382 --http-no-cache [true|false]
384 Send Cache-Control: no-cache and Pragma: no-cache header to
385 avoid cached content. If false is given, these headers are not
386 sent and you can add Cache-Control header with a directive you
387 like using --header option. Default: false
388 --http-user=<USER>
390 Set HTTP user. This affects all URIs.
391 --http-passwd=<PASSWD>
393 Set HTTP password. This affects all URIs.
394 --http-proxy=<PROXY>
396 Use a proxy server for HTTP. To override a previously defined
397 proxy, use "". See also the --all-proxy option. This affects
398 all http downloads. The format of PROXY is [http://][USER:PASS‐
399 WORD@]HOST[:PORT]
400 --http-proxy-passwd=<PASSWD>
402 Set password for --http-proxy.
403 --http-proxy-user=<USER>
405 Set user for --http-proxy.
406 --https-proxy=<PROXY>
408 Use a proxy server for HTTPS. To override a previously defined
409 proxy, use "". See also the --all-proxy option. This affects
410 all https download. The format of PROXY is [http://][USER:PASS‐
411 WORD@]HOST[:PORT]
412 --https-proxy-passwd=<PASSWD>
414 Set password for --https-proxy.
415 --https-proxy-user=<USER>
417 Set user for --https-proxy.
418 --private-key=<FILE>
420 Use the private key in FILE. The private key must be decrypted
421 and in PEM format. The behavior when encrypted one is given is
422 undefined. See also --certificate option.
423 --referer=<REFERER>
425 Set an http referrer (Referer). This affects all http/https
426 downloads. If * is given, the download URI is also used as the
427 referrer. This may be useful when used together with the
428 --parameterized-uri option.
429 --enable-http-keep-alive [true|false]
431 Enable HTTP/1.1 persistent connection. Default: true
432 --enable-http-pipelining [true|false]
434 Enable HTTP/1.1 pipelining. Default: false
435 NOTE:
437 In performance perspective, there is usually no advantage to
438 enable this option.
439 --header=<HEADER>
441 Append HEADER to HTTP request header. You can use this option
442 repeatedly to specify more than one header:
443 $ aria2c --header="X-A: b78" --header="X-B: 9J1" "http://host/file"
445 --load-cookies=<FILE>
447 Load Cookies from FILE using the Firefox3 format (SQLite3),
448 Chromium/Google Chrome (SQLite3) and the Mozilla/Fire‐
449 fox(1.x/2.x)/Netscape format.
450 NOTE:
452 If aria2 is built without libsqlite3, then it doesn't support
453 Firefox3 and Chromium/Google Chrome cookie format.
454 --save-cookies=<FILE>
456 Save Cookies to FILE in Mozilla/Firefox(1.x/2.x)/ Netscape for‐
457 mat. If FILE already exists, it is overwritten. Session Cookies
458 are also saved and their expiry values are treated as 0. Possi‐
459 ble Values: /path/to/file
460 --use-head [true|false]
462 Use HEAD method for the first request to the HTTP server.
463 Default: false
464 -U, --user-agent=<USER_AGENT>
466 Set user agent for HTTP(S) downloads. Default: aria2/$VERSION,
467 $VERSION is replaced by package version.
468 FTP/SFTP Specific Options
470 --ftp-user=<USER>
471 Set FTP user. This affects all URIs. Default: anonymous
472 --ftp-passwd=<PASSWD>
474 Set FTP password. This affects all URIs. If user name is embed‐
475 ded but password is missing in URI, aria2 tries to resolve pass‐
476 word using .netrc. If password is found in .netrc, then use it
477 as password. If not, use the password specified in this option.
478 Default: ARIA2USER@
479 -p, --ftp-pasv [true|false]
481 Use the passive mode in FTP. If false is given, the active mode
482 will be used. Default: true
483 NOTE:
485 This option is ignored for SFTP transfer.
486 --ftp-proxy=<PROXY>
488 Use a proxy server for FTP. To override a previously defined
489 proxy, use "". See also the --all-proxy option. This affects
490 all ftp downloads. The format of PROXY is [http://][USER:PASS‐
491 WORD@]HOST[:PORT]
492 --ftp-proxy-passwd=<PASSWD>
494 Set password for --ftp-proxy option.
495 --ftp-proxy-user=<USER>
497 Set user for --ftp-proxy option.
498 --ftp-type=<TYPE>
500 Set FTP transfer type. TYPE is either binary or ascii. Default:
501 binary
502 NOTE:
504 This option is ignored for SFTP transfer.
505 --ftp-reuse-connection [true|false]
507 Reuse connection in FTP. Default: true
508 --ssh-host-key-md=<TYPE>=<DIGEST>
510 Set checksum for SSH host public key. TYPE is hash type. The
511 supported hash type is sha-1 or md5. DIGEST is hex digest. For
512 example: sha-1=b030503d4de4539dc7885e6f0f5e256704edf4c3. This
513 option can be used to validate server's public key when SFTP is
514 used. If this option is not set, which is default, no validation
515 takes place.
516 BitTorrent/Metalink Options
518 --select-file=<INDEX>...
519 Set file to download by specifying its index. You can find the
520 file index using the --show-files option. Multiple indexes can
521 be specified by using ,, for example: 3,6. You can also use -
522 to specify a range: 1-5. , and - can be used together: 1-5,8,9.
523 When used with the -M option, index may vary depending on the
524 query (see --metalink-* options).
525 NOTE:
527 In multi file torrent, the adjacent files specified by this
528 option may also be downloaded. This is by design, not a bug.
529 A single piece may include several files or part of files,
530 and aria2 writes the piece to the appropriate files.
531 -S, --show-files [true|false]
533 Print file listing of ".torrent", ".meta4" and ".metalink" file
534 and exit. In case of ".torrent" file, additional information
535 (infohash, piece length, etc) is also printed.
536 BitTorrent Specific Options
538 --bt-detach-seed-only [true|false]
539 Exclude seed only downloads when counting concurrent active
540 downloads (See -j option). This means that if -j3 is given and
541 this option is turned on and 3 downloads are active and one of
542 those enters seed mode, then it is excluded from active download
543 count (thus it becomes 2), and the next download waiting in
544 queue gets started. But be aware that seeding item is still rec‐
545 ognized as active download in RPC method. Default: false
546 --bt-enable-hook-after-hash-check [true|false]
548 Allow hook command invocation after hash check (see -V option)
549 in BitTorrent download. By default, when hash check succeeds,
550 the command given by --on-bt-download-complete is executed. To
551 disable this action, give false to this option. Default: true
552 --bt-enable-lpd [true|false]
554 Enable Local Peer Discovery. If a private flag is set in a tor‐
555 rent, aria2 doesn't use this feature for that download even if
556 true is given. Default: false
557 --bt-exclude-tracker=<URI>[,...]
559 Comma separated list of BitTorrent tracker's announce URI to
560 remove. You can use special value * which matches all URIs, thus
561 removes all announce URIs. When specifying * in shell com‐
562 mand-line, don't forget to escape or quote it. See also
563 --bt-tracker option.
564 --bt-external-ip=<IPADDRESS>
566 Specify the external IP address to use in BitTorrent download
567 and DHT. It may be sent to BitTorrent tracker. For DHT, this
568 option should be set to report that local node is downloading a
569 particular torrent. This is critical to use DHT in a private
570 network. Although this function is named external, it can accept
571 any kind of IP addresses.
572 --bt-force-encryption [true|false]
574 Requires BitTorrent message payload encryption with arc4. This
575 is a shorthand of --bt-require-crypto
576 --bt-min-crypto-level=arc4. This option does not change the
577 option value of those options. If true is given, deny legacy
578 BitTorrent handshake and only use Obfuscation handshake and
579 always encrypt message payload. Default: false
580 --bt-hash-check-seed [true|false]
582 If true is given, after hash check using --check-integrity
583 option and file is complete, continue to seed file. If you want
584 to check file and download it only when it is damaged or incom‐
585 plete, set this option to false. This option has effect only on
586 BitTorrent download. Default: true
587 --bt-load-saved-metadata [true|false]
589 Before getting torrent metadata from DHT when downloading with
590 magnet link, first try to read file saved by --bt-save-metadata
591 option. If it is successful, then skip downloading metadata
592 from DHT. Default: false
593 --bt-lpd-interface=<INTERFACE>
595 Use given interface for Local Peer Discovery. If this option is
596 not specified, the default interface is chosen. You can specify
597 interface name and IP address. Possible Values: interface, IP
598 address
599 --bt-max-open-files=<NUM>
601 Specify maximum number of files to open in multi-file BitTor‐
602 rent/Metalink download globally. Default: 100
603 --bt-max-peers=<NUM>
605 Specify the maximum number of peers per torrent. 0 means unlim‐
606 ited. See also --bt-request-peer-speed-limit option. Default:
607 55
608 --bt-metadata-only [true|false]
610 Download meta data only. The file(s) described in meta data will
611 not be downloaded. This option has effect only when BitTorrent
612 Magnet URI is used. See also --bt-save-metadata option.
613 Default: false
614 --bt-min-crypto-level=plain|arc4
616 Set minimum level of encryption method. If several encryption
617 methods are provided by a peer, aria2 chooses the lowest one
618 which satisfies the given level. Default: plain
619 --bt-prioritize-piece=head[=<SIZE>],tail[=<SIZE>]
621 Try to download first and last pieces of each file first. This
622 is useful for previewing files. The argument can contain 2 key‐
623 words: head and tail. To include both keywords, they must be
624 separated by comma. These keywords can take one parameter, SIZE.
625 For example, if head=<SIZE> is specified, pieces in the range of
626 first SIZE bytes of each file get higher priority. tail=<SIZE>
627 means the range of last SIZE bytes of each file. SIZE can
628 include K or M (1K = 1024, 1M = 1024K). If SIZE is omitted,
629 SIZE=1M is used.
630 --bt-remove-unselected-file [true|false]
632 Removes the unselected files when download is completed in Bit‐
633 Torrent. To select files, use --select-file option. If it is not
634 used, all files are assumed to be selected. Please use this
635 option with care because it will actually remove files from your
636 disk. Default: false
637 --bt-require-crypto [true|false]
639 If true is given, aria2 doesn't accept and establish connection
640 with legacy BitTorrent handshake(\19BitTorrent protocol). Thus
641 aria2 always uses Obfuscation handshake. Default: false
642 --bt-request-peer-speed-limit=<SPEED>
644 If the whole download speed of every torrent is lower than
645 SPEED, aria2 temporarily increases the number of peers to try
646 for more download speed. Configuring this option with your pre‐
647 ferred download speed can increase your download speed in some
648 cases. You can append K or M (1K = 1024, 1M = 1024K). Default:
649 50K
650 --bt-save-metadata [true|false]
652 Save meta data as ".torrent" file. This option has effect only
653 when BitTorrent Magnet URI is used. The file name is hex
654 encoded info hash with suffix ".torrent". The directory to be
655 saved is the same directory where download file is saved. If the
656 same file already exists, meta data is not saved. See also
657 --bt-metadata-only option. Default: false
658 --bt-seed-unverified [true|false]
660 Seed previously downloaded files without verifying piece hashes.
661 Default: false
662 --bt-stop-timeout=<SEC>
664 Stop BitTorrent download if download speed is 0 in consecutive
665 SEC seconds. If 0 is given, this feature is disabled. Default:
666 0
667 --bt-tracker=<URI>[,...]
669 Comma separated list of additional BitTorrent tracker's announce
670 URI. These URIs are not affected by --bt-exclude-tracker option
671 because they are added after URIs in --bt-exclude-tracker option
672 are removed.
673 --bt-tracker-connect-timeout=<SEC>
675 Set the connect timeout in seconds to establish connection to
676 tracker. After the connection is established, this option makes
677 no effect and --bt-tracker-timeout option is used instead.
678 Default: 60
679 --bt-tracker-interval=<SEC>
681 Set the interval in seconds between tracker requests. This com‐
682 pletely overrides interval value and aria2 just uses this value
683 and ignores the min interval and interval value in the response
684 of tracker. If 0 is set, aria2 determines interval based on the
685 response of tracker and the download progress. Default: 0
686 --bt-tracker-timeout=<SEC>
688 Set timeout in seconds. Default: 60
689 --dht-entry-point=<HOST>:<PORT>
691 Set host and port as an entry point to IPv4 DHT network.
692 --dht-entry-point6=<HOST>:<PORT>
694 Set host and port as an entry point to IPv6 DHT network.
695 --dht-file-path=<PATH>
697 Change the IPv4 DHT routing table file to PATH. Default:
698 $HOME/.aria2/dht.dat if present, otherwise
699 $XDG_CACHE_HOME/aria2/dht.dat.
700 --dht-file-path6=<PATH>
702 Change the IPv6 DHT routing table file to PATH. Default:
703 $HOME/.aria2/dht6.dat if present, otherwise
704 $XDG_CACHE_HOME/aria2/dht6.dat.
705 --dht-listen-addr6=<ADDR>
707 Specify address to bind socket for IPv6 DHT. It should be a
708 global unicast IPv6 address of the host.
709 --dht-listen-port=<PORT>...
711 Set UDP listening port used by DHT(IPv4, IPv6) and UDP tracker.
712 Multiple ports can be specified by using ,, for example:
713 6881,6885. You can also use - to specify a range: 6881-6999. ,
714 and - can be used together. Default: 6881-6999
715 NOTE:
717 Make sure that the specified ports are open for incoming UDP
718 traffic.
719 --dht-message-timeout=<SEC>
721 Set timeout in seconds. Default: 10
722 --enable-dht [true|false]
724 Enable IPv4 DHT functionality. It also enables UDP tracker sup‐
725 port. If a private flag is set in a torrent, aria2 doesn't use
726 DHT for that download even if true is given. Default: true
727 --enable-dht6 [true|false]
729 Enable IPv6 DHT functionality. If a private flag is set in a
730 torrent, aria2 doesn't use DHT for that download even if true is
731 given. Use --dht-listen-port option to specify port number to
732 listen on. See also --dht-listen-addr6 option.
733 --enable-peer-exchange [true|false]
735 Enable Peer Exchange extension. If a private flag is set in a
736 torrent, this feature is disabled for that download even if true
737 is given. Default: true
738 --follow-torrent=true|false|mem
740 If true or mem is specified, when a file whose suffix is .tor‐
741 rent or content type is application/x-bittorrent is downloaded,
742 aria2 parses it as a torrent file and downloads files mentioned
743 in it. If mem is specified, a torrent file is not written to
744 the disk, but is just kept in memory. If false is specified,
745 the .torrent file is downloaded to the disk, but is not parsed
746 as a torrent and its contents are not downloaded. Default: true
747 -O, --index-out=<INDEX>=<PATH>
749 Set file path for file with index=INDEX. You can find the file
750 index using the --show-files option. PATH is a relative path to
751 the path specified in --dir option. You can use this option mul‐
752 tiple times. Using this option, you can specify the output file
753 names of BitTorrent downloads.
754 --listen-port=<PORT>...
756 Set TCP port number for BitTorrent downloads. Multiple ports
757 can be specified by using ,, for example: 6881,6885. You can
758 also use - to specify a range: 6881-6999. , and - can be used
759 together: 6881-6889,6999. Default: 6881-6999
760 NOTE:
762 Make sure that the specified ports are open for incoming TCP
763 traffic.
764 --max-overall-upload-limit=<SPEED>
766 Set max overall upload speed in bytes/sec. 0 means unre‐
767 stricted. You can append K or M (1K = 1024, 1M = 1024K). To
768 limit the upload speed per torrent, use --max-upload-limit
769 option. Default: 0
770 -u, --max-upload-limit=<SPEED>
772 Set max upload speed per each torrent in bytes/sec. 0 means
773 unrestricted. You can append K or M (1K = 1024, 1M = 1024K).
774 To limit the overall upload speed, use
775 --max-overall-upload-limit option. Default: 0
776 --peer-id-prefix=<PEER_ID_PREFIX>
778 Specify the prefix of peer ID. The peer ID in BitTorrent is 20
779 byte length. If more than 20 bytes are specified, only first 20
780 bytes are used. If less than 20 bytes are specified, random byte
781 data are added to make its length 20 bytes.
782 Default: A2-$MAJOR-$MINOR-$PATCH-, $MAJOR, $MINOR and $PATCH are
784 replaced by major, minor and patch version number respectively.
785 For instance, aria2 version 1.18.8 has prefix ID A2-1-18-8-.
786 --peer-agent=<PEER_AGENT>
788 Specify the string used during the bitorrent extended handshake
789 for the peer's client version.
790 Default: aria2/$MAJOR.$MINOR.$PATCH, $MAJOR, $MINOR and $PATCH
792 are replaced by major, minor and patch version number respec‐
793 tively. For instance, aria2 version 1.18.8 has peer agent
794 aria2/1.18.8.
795 --seed-ratio=<RATIO>
797 Specify share ratio. Seed completed torrents until share ratio
798 reaches RATIO. You are strongly encouraged to specify equals or
799 more than 1.0 here. Specify 0.0 if you intend to do seeding
800 regardless of share ratio. If --seed-time option is specified
801 along with this option, seeding ends when at least one of the
802 conditions is satisfied. Default: 1.0
803 --seed-time=<MINUTES>
805 Specify seeding time in (fractional) minutes. Also see the
806 --seed-ratio option.
807 NOTE:
809 Specifying --seed-time=0 disables seeding after download com‐
810 pleted.
811 -T, --torrent-file=<TORRENT_FILE>
813 The path to the ".torrent" file. You are not required to use
814 this option because you can specify ".torrent" files without
815 --torrent-file.
816 Metalink Specific Options
818 --follow-metalink=true|false|mem
819 If true or mem is specified, when a file whose suffix is .meta4
820 or .metalink or content type of application/metalink4+xml or
821 application/metalink+xml is downloaded, aria2 parses it as a
822 metalink file and downloads files mentioned in it. If mem is
823 specified, a metalink file is not written to the disk, but is
824 just kept in memory. If false is specified, the .metalink file
825 is downloaded to the disk, but is not parsed as a metalink file
826 and its contents are not downloaded. Default: true
827 --metalink-base-uri=<URI>
829 Specify base URI to resolve relative URI in metalink:url and
830 metalink:metaurl element in a metalink file stored in local
831 disk. If URI points to a directory, URI must end with /.
832 -M, --metalink-file=<METALINK_FILE>
834 The file path to ".meta4" and ".metalink" file. Reads input from
835 stdin when - is specified. You are not required to use this
836 option because you can specify ".metalink" files without
837 --metalink-file.
838 --metalink-language=<LANGUAGE>
840 The language of the file to download.
841 --metalink-location=<LOCATION>[,...]
843 The location of the preferred server. A comma-delimited list of
844 locations is acceptable, for example, jp,us.
845 --metalink-os=<OS>
847 The operating system of the file to download.
848 --metalink-version=<VERSION>
850 The version of the file to download.
851 --metalink-preferred-protocol=<PROTO>
853 Specify preferred protocol. The possible values are http,
854 https, ftp and none. Specify none to disable this feature.
855 Default: none
856 --metalink-enable-unique-protocol [true|false]
858 If true is given and several protocols are available for a mir‐
859 ror in a metalink file, aria2 uses one of them. Use
860 --metalink-preferred-protocol option to specify the preference
861 of protocol. Default: true
862 RPC Options
864 --enable-rpc [true|false]
865 Enable JSON-RPC/XML-RPC server. It is strongly recommended to
866 set secret authorization token using --rpc-secret option. See
867 also --rpc-listen-port option. Default: false
868 --pause [true|false]
870 Pause download after added. This option is effective only when
871 --enable-rpc=true is given. Default: false
872 --pause-metadata [true|false]
874 Pause downloads created as a result of metadata download. There
875 are 3 types of metadata downloads in aria2: (1) downloading
876 .torrent file. (2) downloading torrent metadata using magnet
877 link. (3) downloading metalink file. These metadata downloads
878 will generate downloads using their metadata. This option pauses
879 these subsequent downloads. This option is effective only when
880 --enable-rpc=true is given. Default: false
881 --rpc-allow-origin-all [true|false]
883 Add Access-Control-Allow-Origin header field with value * to the
884 RPC response. Default: false
885 --rpc-certificate=<FILE>
887 Use the certificate in FILE for RPC server. The certificate must
888 be either in PKCS12 (.p12, .pfx) or in PEM format.
889 PKCS12 files must contain the certificate, a key and optionally
891 a chain of additional certificates. Only PKCS12 files with a
892 blank import password can be opened!
893 When using PEM, you have to specify the private key via
895 --rpc-private-key as well. Use --rpc-secure option to enable
896 encryption.
897 NOTE:
899 WinTLS does not support PEM files at the moment. Users have
900 to use PKCS12 files.
901 NOTE:
903 AppleTLS users should use the KeyChain Access utility to
904 first generate a self-signed SSL-Server certificate, e.g.
905 using the wizard, and get the SHA-1 fingerprint from the
906 Information dialog corresponding to that new certificate. To
907 start aria2c with --rpc-secure use --rpc-certificate=<SHA-1>.
908 Alternatively PKCS12 files are also supported. PEM files,
909 however, are not supported.
910 --rpc-listen-all [true|false]
912 Listen incoming JSON-RPC/XML-RPC requests on all network inter‐
913 faces. If false is given, listen only on local loopback inter‐
914 face. Default: false
915 --rpc-listen-port=<PORT>
917 Specify a port number for JSON-RPC/XML-RPC server to listen to.
918 Possible Values: 1024 -65535 Default: 6800
919 --rpc-max-request-size=<SIZE>
921 Set max size of JSON-RPC/XML-RPC request. If aria2 detects the
922 request is more than SIZE bytes, it drops connection. Default:
923 2M
924 --rpc-passwd=<PASSWD>
926 Set JSON-RPC/XML-RPC password.
927 WARNING:
929 --rpc-passwd option will be deprecated in the future release.
930 Migrate to --rpc-secret option as soon as possible.
931 --rpc-private-key=<FILE>
933 Use the private key in FILE for RPC server. The private key
934 must be decrypted and in PEM format. Use --rpc-secure option to
935 enable encryption. See also --rpc-certificate option.
936 --rpc-save-upload-metadata [true|false]
938 Save the uploaded torrent or metalink meta data in the directory
939 specified by --dir option. The file name consists of SHA-1 hash
940 hex string of meta data plus extension. For torrent, the exten‐
941 sion is '.torrent'. For metalink, it is '.meta4'. If false is
942 given to this option, the downloads added by aria2.addTorrent()
943 or aria2.addMetalink() will not be saved by --save-session
944 option. Default: true
945 --rpc-secret=<TOKEN>
947 Set RPC secret authorization token. Read RPC authorization
948 secret token to know how this option value is used.
949 --rpc-secure [true|false]
951 RPC transport will be encrypted by SSL/TLS. The RPC clients
952 must use https scheme to access the server. For WebSocket
953 client, use wss scheme. Use --rpc-certificate and
954 --rpc-private-key options to specify the server certificate and
955 private key.
956 --rpc-user=<USER>
958 Set JSON-RPC/XML-RPC user.
959 WARNING:
961 --rpc-user option will be deprecated in the future release.
962 Migrate to --rpc-secret option as soon as possible.
963 Advanced Options
965 --allow-overwrite [true|false]
966 Restart download from scratch if the corresponding control file
967 doesn't exist. See also --auto-file-renaming option. Default:
968 false
969 --allow-piece-length-change [true|false]
971 If false is given, aria2 aborts download when a piece length is
972 different from one in a control file. If true is given, you can
973 proceed but some download progress will be lost. Default: false
974 --always-resume [true|false]
976 Always resume download. If true is given, aria2 always tries to
977 resume download and if resume is not possible, aborts download.
978 If false is given, when all given URIs do not support resume or
979 aria2 encounters N URIs which does not support resume (N is the
980 value specified using --max-resume-failure-tries option), aria2
981 downloads file from scratch. See --max-resume-failure-tries
982 option. Default: true
983 --async-dns [true|false]
985 Enable asynchronous DNS. Default: true
986 --async-dns-server=<IPADDRESS>[,...]
988 Comma separated list of DNS server address used in asynchronous
989 DNS resolver. Usually asynchronous DNS resolver reads DNS server
990 addresses from /etc/resolv.conf. When this option is used, it
991 uses DNS servers specified in this option instead of ones in
992 /etc/resolv.conf. You can specify both IPv4 and IPv6 address.
993 This option is useful when the system does not have
994 /etc/resolv.conf and user does not have the permission to create
995 it.
996 --auto-file-renaming [true|false]
998 Rename file name if the same file already exists. This option
999 works only in HTTP(S)/FTP download. The new file name has a dot
1000 and a number(1..9999) appended after the name, but before the
1001 file extension, if any. Default: true
1002 --auto-save-interval=<SEC>
1004 Save a control file(*.aria2) every SEC seconds. If 0 is given,
1005 a control file is not saved during download. aria2 saves a con‐
1006 trol file when it stops regardless of the value. The possible
1007 values are between 0 to 600. Default: 60
1008 --conditional-get [true|false]
1010 Download file only when the local file is older than remote
1011 file. This function only works with HTTP(S) downloads only. It
1012 does not work if file size is specified in Metalink. It also
1013 ignores Content-Disposition header. If a control file exists,
1014 this option will be ignored. This function uses If-Modi‐
1015 fied-Since header to get only newer file conditionally. When
1016 getting modification time of local file, it uses user supplied
1017 file name (see --out option) or file name part in URI if --out
1018 is not specified. To overwrite existing file, --allow-overwrite
1019 is required. Default: false
1020 --conf-path=<PATH>
1022 Change the configuration file path to PATH. Default:
1023 $HOME/.aria2/aria2.conf if present, otherwise $XDG_CON‐
1024 FIG_HOME/aria2/aria2.conf.
1025 --console-log-level=<LEVEL>
1027 Set log level to output to console. LEVEL is either debug,
1028 info, notice, warn or error. Default: notice
1029 --content-disposition-default-utf8 [true|false]
1031 Handle quoted string in Content-Disposition header as UTF-8
1032 instead of ISO-8859-1, for example, the filename parameter, but
1033 not the extended version filename*. Default: false
1034 -D, --daemon [true|false]
1036 Run as daemon. The current working directory will be changed to
1037 / and standard input, standard output and standard error will be
1038 redirected to /dev/null. Default: false
1039 --deferred-input [true|false]
1041 If true is given, aria2 does not read all URIs and options from
1042 file specified by --input-file option at startup, but it reads
1043 one by one when it needs later. This may reduce memory usage if
1044 input file contains a lot of URIs to download. If false is
1045 given, aria2 reads all URIs and options at startup. Default:
1046 false
1047 WARNING:
1049 --deferred-input option will be disabled when --save-session
1050 is used together.
1051 --disable-ipv6 [true|false]
1053 Disable IPv6. This is useful if you have to use broken DNS and
1054 want to avoid terribly slow AAAA record lookup. Default: false
1055 --disk-cache=<SIZE>
1057 Enable disk cache. If SIZE is 0, the disk cache is disabled.
1058 This feature caches the downloaded data in memory, which grows
1059 to at most SIZE bytes. The cache storage is created for aria2
1060 instance and shared by all downloads. The one advantage of the
1061 disk cache is reduce the disk I/O because the data are written
1062 in larger unit and it is reordered by the offset of the file.
1063 If hash checking is involved and the data are cached in memory,
1064 we don't need to read them from the disk. SIZE can include K or
1065 M (1K = 1024, 1M = 1024K). Default: 16M
1066 --download-result=<OPT>
1068 This option changes the way Download Results is formatted. If
1069 OPT is default, print GID, status, average download speed and
1070 path/URI. If multiple files are involved, path/URI of first
1071 requested file is printed and remaining ones are omitted. If
1072 OPT is full, print GID, status, average download speed, percent‐
1073 age of progress and path/URI. The percentage of progress and
1074 path/URI are printed for each requested file in each row. If
1075 OPT is hide, Download Results is hidden. Default: default
1076 --dscp=<DSCP>
1078 Set DSCP value in outgoing IP packets of BitTorrent traffic for
1079 QoS. This parameter sets only DSCP bits in TOS field of IP pack‐
1080 ets, not the whole field. If you take values from
1081 /usr/include/netinet/ip.h divide them by 4 (otherwise values
1082 would be incorrect, e.g. your CS1 class would turn into CS4). If
1083 you take commonly used values from RFC, network vendors' docu‐
1084 mentation, Wikipedia or any other source, use them as they are.
1085 --rlimit-nofile=<NUM>
1087 Set the soft limit of open file descriptors. This open will
1088 only have effect when:
1089 a. The system supports it (posix)
1091 b. The limit does not exceed the hard limit.
1093 c. The specified limit is larger than the current soft limit.
1095 This is equivalent to setting nofile via ulimit, except that it
1097 will never decrease the limit.
1098 This option is only available on systems supporting the rlimit
1100 API.
1101 --enable-color [true|false]
1103 Enable color output for a terminal. Default: true
1104 --enable-mmap [true|false]
1106 Map files into memory. This option may not work if the file
1107 space is not pre-allocated. See --file-allocation.
1108 Default: false
1110 --event-poll=<POLL>
1112 Specify the method for polling events. The possible values are
1113 epoll, kqueue, port, poll and select. For each epoll, kqueue,
1114 port and poll, it is available if system supports it. epoll is
1115 available on recent Linux. kqueue is available on various *BSD
1116 systems including Mac OS X. port is available on Open Solaris.
1117 The default value may vary depending on the system you use.
1118 --file-allocation=<METHOD>
1120 Specify file allocation method. none doesn't pre-allocate file
1121 space. prealloc pre-allocates file space before download begins.
1122 This may take some time depending on the size of the file. If
1123 you are using newer file systems such as ext4 (with extents sup‐
1124 port), btrfs, xfs or NTFS(MinGW build only), falloc is your best
1125 choice. It allocates large(few GiB) files almost instantly.
1126 Don't use falloc with legacy file systems such as ext3 and FAT32
1127 because it takes almost same time as prealloc and it blocks
1128 aria2 entirely until allocation finishes. falloc may not be
1129 available if your system doesn't have posix_fallocate(3) func‐
1130 tion. trunc uses ftruncate(2) system call or platform-specific
1131 counterpart to truncate a file to a specified length.
1132 Possible Values: none, prealloc, trunc, falloc Default: prealloc
1134 WARNING:
1136 Using trunc seemingly allocates disk space very quickly, but
1137 what it actually does is that it sets file length metadata in
1138 file system, and does not allocate disk space at all. This
1139 means that it does not help avoiding fragmentation.
1140 NOTE:
1142 In multi file torrent downloads, the files adjacent forward
1143 to the specified files are also allocated if they share the
1144 same piece.
1145 --force-save [true|false]
1147 Save download with --save-session option even if the download is
1148 completed or removed. This option also saves control file in
1149 that situations. This may be useful to save BitTorrent seeding
1150 which is recognized as completed state. Default: false
1151 --save-not-found [true|false]
1153 Save download with --save-session option even if the file was
1154 not found on the server. This option also saves control file in
1155 that situations. Default: true
1156 --gid=<GID>
1158 Set GID manually. aria2 identifies each download by the ID
1159 called GID. The GID must be hex string of 16 characters, thus
1160 [0-9a-zA-Z] are allowed and leading zeros must not be stripped.
1161 The GID all 0 is reserved and must not be used. The GID must be
1162 unique, otherwise error is reported and the download is not
1163 added. This option is useful when restoring the sessions saved
1164 using --save-session option. If this option is not used, new GID
1165 is generated by aria2.
1166 --hash-check-only [true|false]
1168 If true is given, after hash check using --check-integrity
1169 option, abort download whether or not download is complete.
1170 Default: false
1171 --human-readable [true|false]
1173 Print sizes and speed in human readable format (e.g., 1.2Ki,
1174 3.4Mi) in the console readout. Default: true
1175 --interface=<INTERFACE>
1177 Bind sockets to given interface. You can specify interface name,
1178 IP address and host name. Possible Values: interface, IP
1179 address, host name
1180 NOTE:
1182 If an interface has multiple addresses, it is highly recom‐
1183 mended to specify IP address explicitly. See also
1184 --disable-ipv6. If your system doesn't have getifaddrs(3),
1185 this option doesn't accept interface name.
1186 --keep-unfinished-download-result [true|false]
1188 Keep unfinished download results even if doing so exceeds
1189 --max-download-result. This is useful if all unfinished down‐
1190 loads must be saved in session file (see --save-session option).
1191 Please keep in mind that there is no upper bound to the number
1192 of unfinished download result to keep. If that is undesirable,
1193 turn this option off. Default: true
1194 --max-download-result=<NUM>
1196 Set maximum number of download result kept in memory. The down‐
1197 load results are completed/error/removed downloads. The download
1198 results are stored in FIFO queue and it can store at most NUM
1199 download results. When queue is full and new download result is
1200 created, oldest download result is removed from the front of the
1201 queue and new one is pushed to the back. Setting big number in
1202 this option may result high memory consumption after thousands
1203 of downloads. Specifying 0 means no download result is kept.
1204 Note that unfinished downloads are kept in memory regardless of
1205 this option value. See --keep-unfinished-download-result option.
1206 Default: 1000
1207 --max-mmap-limit=<SIZE>
1209 Set the maximum file size to enable mmap (see --enable-mmap
1210 option). The file size is determined by the sum of all files
1211 contained in one download. For example, if a download contains 5
1212 files, then file size is the total size of those files. If file
1213 size is strictly greater than the size specified in this option,
1214 mmap will be disabled. Default: 9223372036854775807
1215 --max-resume-failure-tries=<N>
1217 When used with --always-resume=false, aria2 downloads file from
1218 scratch when aria2 detects N number of URIs that does not sup‐
1219 port resume. If N is 0, aria2 downloads file from scratch when
1220 all given URIs do not support resume. See --always-resume
1221 option. Default: 0
1222 --min-tls-version=<VERSION>
1224 Specify minimum SSL/TLS version to enable. Possible Values:
1225 SSLv3, TLSv1, TLSv1.1, TLSv1.2 Default: TLSv1
1226 --multiple-interface=<INTERFACES>
1228 Comma separated list of interfaces to bind sockets to. Requests
1229 will be splited among the interfaces to achieve link aggrega‐
1230 tion. You can specify interface name, IP address and hostname.
1231 If --interface is used, this option will be ignored. Possible
1232 Values: interface, IP address, hostname
1233 --log-level=<LEVEL>
1235 Set log level to output. LEVEL is either debug, info, notice,
1236 warn or error. Default: debug
1237 --on-bt-download-complete=<COMMAND>
1239 For BitTorrent, a command specified in --on-download-complete is
1240 called after download completed and seeding is over. On the
1241 other hand, this option set the command to be executed after
1242 download completed but before seeding. See Event Hook for more
1243 details about COMMAND. Possible Values: /path/to/command
1244 --on-download-complete=<COMMAND>
1246 Set the command to be executed after download completed. See
1247 Event Hook for more details about COMMAND. See also
1248 --on-download-stop option. Possible Values: /path/to/command
1249 --on-download-error=<COMMAND>
1251 Set the command to be executed after download aborted due to
1252 error. See Event Hook for more details about COMMAND. See also
1253 --on-download-stop option. Possible Values: /path/to/command
1254 --on-download-pause=<COMMAND>
1256 Set the command to be executed after download was paused. See
1257 Event Hook for more details about COMMAND. Possible Values:
1258 /path/to/command
1259 --on-download-start=<COMMAND>
1261 Set the command to be executed after download got started. See
1262 Event Hook for more details about COMMAND. Possible Values:
1263 /path/to/command
1264 --on-download-stop=<COMMAND>
1266 Set the command to be executed after download stopped. You can
1267 override the command to be executed for particular download
1268 result using --on-download-complete and --on-download-error. If
1269 they are specified, command specified in this option is not exe‐
1270 cuted. See Event Hook for more details about COMMAND. Possible
1271 Values: /path/to/command
1272 --optimize-concurrent-downloads [true|false|<A>:<B>]
1274 Optimizes the number of concurrent downloads according to the
1275 bandwidth available. aria2 uses the download speed observed in
1276 the previous downloads to adapt the number of downloads launched
1277 in parallel according to the rule N = A + B Log10(speed in
1278 Mbps). The coefficients A and B can be customized in the option
1279 arguments with A and B separated by a colon. The default values
1280 (A=5, B=25) lead to using typically 5 parallel downloads on
1281 1Mbps networks and above 50 on 100Mbps networks. The number of
1282 parallel downloads remains constrained under the maximum defined
1283 by the --max-concurrent-downloads parameter. Default: false
1284 --piece-length=<LENGTH>
1286 Set a piece length for HTTP/FTP downloads. This is the boundary
1287 when aria2 splits a file. All splits occur at multiple of this
1288 length. This option will be ignored in BitTorrent downloads. It
1289 will be also ignored if Metalink file contains piece hashes.
1290 Default: 1M
1291 NOTE:
1293 The possible use case of --piece-length option is change the
1294 request range in one HTTP pipelined request. To enable HTTP
1295 pipelining use --enable-http-pipelining.
1296 --show-console-readout [true|false]
1298 Show console readout. Default: true
1299 --stderr [true|false]
1301 Redirect all console output that would be otherwise printed in
1302 stdout to stderr. Default: false
1303 --summary-interval=<SEC>
1305 Set interval in seconds to output download progress summary.
1306 Setting 0 suppresses the output. Default: 60
1307 -Z, --force-sequential [true|false]
1309 Fetch URIs in the command-line sequentially and download each
1310 URI in a separate session, like the usual command-line download
1311 utilities. Default: false
1312 --max-overall-download-limit=<SPEED>
1314 Set max overall download speed in bytes/sec. 0 means unre‐
1315 stricted. You can append K or M (1K = 1024, 1M = 1024K). To
1316 limit the download speed per download, use --max-download-limit
1317 option. Default: 0
1318 --max-download-limit=<SPEED>
1320 Set max download speed per each download in bytes/sec. 0 means
1321 unrestricted. You can append K or M (1K = 1024, 1M = 1024K).
1322 To limit the overall download speed, use
1323 --max-overall-download-limit option. Default: 0
1324 --no-conf [true|false]
1326 Disable loading aria2.conf file.
1327 --no-file-allocation-limit=<SIZE>
1329 No file allocation is made for files whose size is smaller than
1330 SIZE. You can append K or M (1K = 1024, 1M = 1024K). Default:
1331 5M
1332 -P, --parameterized-uri [true|false]
1334 Enable parameterized URI support. You can specify set of parts:
1335 http://{sv1,sv2,sv3}/foo.iso. Also you can specify numeric
1336 sequences with step counter: http://host/image[000-100:2].img.
1337 A step counter can be omitted. If all URIs do not point to the
1338 same file, such as the second example above, -Z option is
1339 required. Default: false
1340 -q, --quiet [true|false]
1342 Make aria2 quiet (no console output). Default: false
1343 --realtime-chunk-checksum [true|false]
1345 Validate chunk of data by calculating checksum while downloading
1346 a file if chunk checksums are provided. Default: true
1347 --remove-control-file [true|false]
1349 Remove control file before download. Using with
1350 --allow-overwrite=true, download always starts from scratch.
1351 This will be useful for users behind proxy server which disables
1352 resume.
1353 --save-session=<FILE>
1355 Save error/unfinished downloads to FILE on exit. You can pass
1356 this output file to aria2c with --input-file option on restart.
1357 If you like the output to be gzipped append a .gz extension to
1358 the file name. Please note that downloads added by
1359 aria2.addTorrent() and aria2.addMetalink() RPC method and whose
1360 meta data could not be saved as a file are not saved. Downloads
1361 removed using aria2.remove() and aria2.forceRemove() will not be
1362 saved. GID is also saved with gid, but there are some restric‐
1363 tions, see below.
1364 NOTE:
1366 Normally, GID of the download itself is saved. But some down‐
1367 loads use meta data (e.g., BitTorrent and Metalink). In this
1368 case, there are some restrictions.
1369 magnet URI, and followed by torrent download
1371 GID of BitTorrent meta data download is saved.
1372 URI to torrent file, and followed by torrent download
1374 GID of torrent file download is saved.
1375 URI to metalink file, and followed by file downloads
1377 described in metalink file
1378 GID of metalink file download is saved.
1379 local torrent file
1381 GID of torrent download is saved.
1382 local metalink file
1384 Any meaningful GID is not saved.
1385 --save-session-interval=<SEC>
1387 Save error/unfinished downloads to a file specified by
1388 --save-session option every SEC seconds. If 0 is given, file
1389 will be saved only when aria2 exits. Default: 0
1390 --socket-recv-buffer-size=<SIZE>
1392 Set the maximum socket receive buffer in bytes. Specifying 0
1393 will disable this option. This value will be set to socket file
1394 descriptor using SO_RCVBUF socket option with setsockopt() call.
1395 Default: 0
1396 --stop=<SEC>
1398 Stop application after SEC seconds has passed. If 0 is given,
1399 this feature is disabled. Default: 0
1400 --stop-with-process=<PID>
1402 Stop application when process PID is not running. This is use‐
1403 ful if aria2 process is forked from a parent process. The parent
1404 process can fork aria2 with its own pid and when parent process
1405 exits for some reason, aria2 can detect it and shutdown itself.
1406 --truncate-console-readout [true|false]
1408 Truncate console readout to fit in a single line. Default: true
1409 -v, --version
1411 Print the version number, copyright and the configuration infor‐
1412 mation and exit.
1413 Notes for Options
1415 Optional arguments
1416 The options that have its argument surrounded by square brackets([])
1417 take an optional argument. Usually omitting the argument is evaluated
1418 to true. If you use short form of these options(such as -V) and give
1419 an argument, then the option name and its argument should be concate‐
1420 nated(e.g. -Vfalse). If any spaces are inserted between the option
1421 name and the argument, the argument will be treated as URI and usually
1422 this is not what you expect.
1423 Units (K and M)
1425 Some options takes K and M to conveniently represent 1024 and 1048576
1426 respectively. aria2 detects these characters in case-insensitive way.
1427 In other words, k and m can be used as well as K and M respectively.
1428 URI, MAGNET, TORRENT_FILE, METALINK_FILE
1430 You can specify multiple URIs in command-line. Unless you specify
1431 --force-sequential option, all URIs must point to the same file or
1432 downloading will fail.
1433 You can specify arbitrary number of BitTorrent Magnet URI. Please note
1435 that they are always treated as a separate download. Both hex encoded
1436 40 characters Info Hash and Base32 encoded 32 characters Info Hash are
1437 supported. The multiple tr parameters are supported. Because BitTor‐
1438 rent Magnet URI is likely to contain & character, it is highly recom‐
1439 mended to always quote URI with single(') or double(") quotation. It
1440 is strongly recommended to enable DHT especially when tr parameter is
1441 missing. See http://www.bittorrent.org/beps/bep_0009.html for more
1442 details about BitTorrent Magnet URI.
1443 You can also specify arbitrary number of torrent files and Metalink
1445 documents stored on a local drive. Please note that they are always
1446 treated as a separate download. Both Metalink4 and Metalink version 3.0
1447 are supported.
1448 You can specify both torrent file with -T option and URIs. By doing
1450 this, you can download a file from both torrent swarm and
1451 HTTP(S)/FTP/SFTP server at the same time, while the data from
1452 HTTP(S)/FTP/SFTP are uploaded to the torrent swarm. For single file
1453 torrents, URI can be a complete URI pointing to the resource or if URI
1454 ends with /, name in torrent file in torrent is added. For multi-file
1455 torrents, name and path are added to form a URI for each file.
1456 NOTE:
1458 Make sure that URI is quoted with single(') or double(") quotation
1459 if it contains & or any characters that have special meaning in
1460 shell.
1461 Resuming Download
1463 Usually, you can resume transfer by just issuing same command (aria2c
1464 URI) if the previous transfer is made by aria2.
1465 If the previous transfer is made by a browser or wget like sequential
1467 download manager, then use --continue option to continue the transfer.
1468 Event Hook
1470 aria2 provides options to specify arbitrary command after specific
1471 event occurred. Currently following options are available:
1472 --on-bt-download-complete, --on-download-pause, --on-download-complete.
1473 --on-download-start, --on-download-error, --on-download-stop.
1474 aria2 passes 3 arguments to specified command when it is executed.
1476 These arguments are: GID, the number of files and file path. For HTTP,
1477 FTP, and SFTP downloads, usually the number of files is 1. BitTorrent
1478 download can contain multiple files. If number of files is more than
1479 one, file path is first one. In other words, this is the value of path
1480 key of first struct whose selected key is true in the response of
1481 aria2.getFiles() RPC method. If you want to get all file paths, con‐
1482 sider to use JSON-RPC/XML-RPC. Please note that file path may change
1483 during download in HTTP because of redirection or Content-Disposition
1484 header.
1485 Let's see an example of how arguments are passed to command:
1487 $ cat hook.sh
1489 #!/bin/sh
1490 echo "Called with [$1] [$2] [$3]"
1491 $ aria2c --on-download-complete hook.sh http://example.org/file.iso
1492 Called with [1] [1] [/path/to/file.iso]
1493
1495 Because aria2 can handle multiple downloads at once, it encounters lots
1496 of errors in a session. aria2 returns the following exit status based
1497 on the last error encountered.
1498 0 If all downloads were successful.
1500 1 If an unknown error occurred.
1502 2 If time out occurred.
1504 3 If a resource was not found.
1506 4 If aria2 saw the specified number of "resource not found" error.
1508 See --max-file-not-found option.
1509 5 If a download aborted because download speed was too slow. See
1511 --lowest-speed-limit option.
1512 6 If network problem occurred.
1514 7 If there were unfinished downloads. This error is only reported
1516 if all finished downloads were successful and there were unfin‐
1517 ished downloads in a queue when aria2 exited by pressing Ctrl-C
1518 by an user or sending TERM or INT signal.
1519 8 If remote server did not support resume when resume was required
1521 to complete download.
1522 9 If there was not enough disk space available.
1524 10 If piece length was different from one in .aria2 control file.
1526 See --allow-piece-length-change option.
1527 11 If aria2 was downloading same file at that moment.
1529 12 If aria2 was downloading same info hash torrent at that moment.
1531 13 If file already existed. See --allow-overwrite option.
1533 14 If renaming file failed. See --auto-file-renaming option.
1535 15 If aria2 could not open existing file.
1537 16 If aria2 could not create new file or truncate existing file.
1539 17 If file I/O error occurred.
1541 18 If aria2 could not create directory.
1543 19 If name resolution failed.
1545 20 If aria2 could not parse Metalink document.
1547 21 If FTP command failed.
1549 22 If HTTP response header was bad or unexpected.
1551 23 If too many redirects occurred.
1553 24 If HTTP authorization failed.
1555 25 If aria2 could not parse bencoded file (usually ".torrent"
1557 file).
1558 26 If ".torrent" file was corrupted or missing information that
1560 aria2 needed.
1561 27 If Magnet URI was bad.
1563 28 If bad/unrecognized option was given or unexpected option argu‐
1565 ment was given.
1566 29 If the remote server was unable to handle the request due to a
1568 temporary overloading or maintenance.
1569 30 If aria2 could not parse JSON-RPC request.
1571 31 Reserved. Not used.
1573 32 If checksum validation failed.
1575 NOTE:
1577 An error occurred in a finished download will not be reported as
1578 exit status.
1579
1581 aria2 recognizes the following environment variables.
1582 http_proxy [http://][USER:PASSWORD@]HOST[:PORT]
1584 Specify proxy server for use in HTTP. Overrides http-proxy
1585 value in configuration file. The command-line option
1586 --http-proxy overrides this value.
1587 https_proxy [http://][USER:PASSWORD@]HOST[:PORT]
1589 Specify proxy server for use in HTTPS. Overrides https-proxy
1590 value in configuration file. The command-line option
1591 --https-proxy overrides this value.
1592 ftp_proxy [http://][USER:PASSWORD@]HOST[:PORT]
1594 Specify proxy server for use in FTP. Overrides ftp-proxy value
1595 in configuration file. The command-line option --ftp-proxy
1596 overrides this value.
1597 all_proxy [http://][USER:PASSWORD@]HOST[:PORT]
1599 Specify proxy server for use if no protocol-specific proxy is
1600 specified. Overrides all-proxy value in configuration file.
1601 The command-line option --all-proxy overrides this value.
1602 NOTE:
1604 Although aria2 accepts ftp:// and https:// scheme in proxy URI, it
1605 simply assumes that http:// is specified and does not change its
1606 behavior based on the specified scheme.
1607 no_proxy [DOMAIN,...]
1609 Specify a comma-separated list of host names, domains and net‐
1610 work addresses with or without a subnet mask where no proxy
1611 should be used. Overrides the no-proxy value in configuration
1612 file. The command-line option --no-proxy overrides this value.
1613
1615 aria2.conf
1616 By default, aria2 checks whether the legacy path
1617 $HOME/.aria2/aria2.conf is present, otherwise it parses $XDG_CON‐
1618 FIG_HOME/aria2/aria2.conf as its configuration file. You can specify
1619 the path to configuration file using --conf-path option. If you don't
1620 want to use the configuration file, use --no-conf option.
1621 The configuration file is a text file and has 1 option per each line.
1623 In each line, you can specify name-value pair in the format:
1624 NAME=VALUE, where name is the long command-line option name without --
1625 prefix. You can use same syntax for the command-line option. The lines
1626 beginning # are treated as comments:
1627 # sample configuration file for aria2c
1629 listen-port=60000
1630 dht-listen-port=60000
1631 seed-ratio=1.0
1632 max-upload-limit=50K
1633 ftp-pasv=true
1634 NOTE:
1636 The confidential information such as user/password might be included
1637 in the configuration file. It is recommended to change file mode
1638 bits of the configuration file (e.g., chmod 600 aria2.conf), so that
1639 other user cannot see the contents of the file.
1640 The environment variables, such as ${HOME}, are expanded by shell.
1642 This means that those variables used in configuration file are not
1643 expanded. However, it is useful to ${HOME} to refer user's home direc‐
1644 tory in configuration file to specify file paths. Therefore, aria2
1645 expands ${HOME} found in the following option values to user's home
1646 directory:
1647 · ca-certificate
1649 · certificate
1651 · dht-file-path
1653 · dht-file-path6
1655 · dir
1657 · input-file
1659 · load-cookies
1661 · log
1663 · metalink-file
1665 · netrc-path
1667 · on-bt-download-complete
1669 · on-download-complete
1671 · on-download-error
1673 · on-download-start
1675 · on-download-stop
1677 · on-download-pause
1679 · out
1681 · private-key
1683 · rpc-certificate
1685 · rpc-private-key
1687 · save-cookies
1689 · save-session
1691 · server-stat-if
1693 · server-stat-of
1695 · torrent-file
1697 Note that this expansion occurs even if the above options are used in
1699 the command-line. This means that expansion may occur 2 times: first,
1700 shell and then aria2c.
1701 dht.dat
1703 Unless the legacy file paths $HOME/.aria2/dht.dat and
1704 $HOME/.aria2/dht6.dat are pointing to existing files, the routing table
1705 of IPv4 DHT is saved to the path $XDG_CACHE_HOME/aria2/dht.dat and the
1706 routing table of IPv6 DHT is saved to the path
1707 $XDG_CACHE_HOME/aria2/dht6.dat.
1708 Netrc
1710 Netrc support is enabled by default for HTTP(S)/FTP/SFTP. To disable
1711 netrc support, specify --no-netrc option. Your .netrc file should have
1712 correct permissions(600).
1713 If machine name starts ., aria2 performs domain-match instead of exact
1715 match. This is an extension of aria2. For example of domain match,
1716 imagine the following .netrc entry:
1717 machine .example.org login myid password mypasswd
1719 aria2.example.org domain-matches .example.org and uses myid and
1721 mypasswd.
1722 Some domain-match example follow: example.net does not domain-match
1724 .example.org. example.org does not domain-match .example.org because of
1725 preceding .. If you want to match example.org, specify example.org.
1726 Control File
1728 aria2 uses a control file to track the progress of a download. A con‐
1729 trol file is placed in the same directory as the downloading file and
1730 its file name is the file name of downloading file with .aria2
1731 appended. For example, if you are downloading file.zip, then the con‐
1732 trol file should be file.zip.aria2. (There is a exception for this
1733 naming convention. If you are downloading a multi torrent, its control
1734 file is the "top directory" name of the torrent with .aria2 appended.
1735 The "top directory" name is a value of "name" key in "info" directory
1736 in a torrent file.)
1737 Usually a control file is deleted once download completed. If aria2
1739 decides that download cannot be resumed(for example, when downloading a
1740 file from a HTTP server which doesn't support resume), a control file
1741 is not created.
1742 Normally if you lose a control file, you cannot resume download. But
1744 if you have a torrent or metalink with chunk checksums for the file,
1745 you can resume the download without a control file by giving -V option
1746 to aria2c in command-line.
1747 Input File
1749 The input file can contain a list of URIs for aria2 to download. You
1750 can specify multiple URIs for a single entity: separate URIs on a sin‐
1751 gle line using the TAB character.
1752 Each line is treated as if it is provided in command-line argument.
1754 Therefore they are affected by --force-sequential and
1755 --parameterized-uri options.
1756 Since URIs in the input file are directly read by aria2, they must not
1758 be quoted with single(') or double(") quotation.
1759 Lines starting with # are treated as comments and skipped.
1761 Additionally, the following options can be specified after each line of
1763 URIs. These optional lines must start with white space(s).
1764 · all-proxy
1766 · all-proxy-passwd
1768 · all-proxy-user
1770 · allow-overwrite
1772 · allow-piece-length-change
1774 · always-resume
1776 · async-dns
1778 · auto-file-renaming
1780 · bt-enable-hook-after-hash-check
1782 · bt-enable-lpd
1784 · bt-exclude-tracker
1786 · bt-external-ip
1788 · bt-force-encryption
1790 · bt-hash-check-seed
1792 · bt-load-saved-metadata
1794 · bt-max-peers
1796 · bt-metadata-only
1798 · bt-min-crypto-level
1800 · bt-prioritize-piece
1802 · bt-remove-unselected-file
1804 · bt-request-peer-speed-limit
1806 · bt-require-crypto
1808 · bt-save-metadata
1810 · bt-seed-unverified
1812 · bt-stop-timeout
1814 · bt-tracker
1816 · bt-tracker-connect-timeout
1818 · bt-tracker-interval
1820 · bt-tracker-timeout
1822 · check-integrity
1824 · checksum
1826 · conditional-get
1828 · connect-timeout
1830 · content-disposition-default-utf8
1832 · continue
1834 · dir
1836 · dry-run
1838 · enable-http-keep-alive
1840 · enable-http-pipelining
1842 · enable-mmap
1844 · enable-peer-exchange
1846 · file-allocation
1848 · follow-metalink
1850 · follow-torrent
1852 · force-save
1854 · ftp-passwd
1856 · ftp-pasv
1858 · ftp-proxy
1860 · ftp-proxy-passwd
1862 · ftp-proxy-user
1864 · ftp-reuse-connection
1866 · ftp-type
1868 · ftp-user
1870 · gid
1872 · hash-check-only
1874 · header
1876 · http-accept-gzip
1878 · http-auth-challenge
1880 · http-no-cache
1882 · http-passwd
1884 · http-proxy
1886 · http-proxy-passwd
1888 · http-proxy-user
1890 · http-user
1892 · https-proxy
1894 · https-proxy-passwd
1896 · https-proxy-user
1898 · index-out
1900 · lowest-speed-limit
1902 · max-connection-per-server
1904 · max-download-limit
1906 · max-file-not-found
1908 · max-mmap-limit
1910 · max-resume-failure-tries
1912 · max-tries
1914 · max-upload-limit
1916 · metalink-base-uri
1918 · metalink-enable-unique-protocol
1920 · metalink-language
1922 · metalink-location
1924 · metalink-os
1926 · metalink-preferred-protocol
1928 · metalink-version
1930 · min-split-size
1932 · no-file-allocation-limit
1934 · no-netrc
1936 · no-proxy
1938 · out
1940 · parameterized-uri
1942 · pause
1944 · pause-metadata
1946 · piece-length
1948 · proxy-method
1950 · realtime-chunk-checksum
1952 · referer
1954 · remote-time
1956 · remove-control-file
1958 · retry-wait
1960 · reuse-uri
1962 · rpc-save-upload-metadata
1964 · seed-ratio
1966 · seed-time
1968 · select-file
1970 · split
1972 · ssh-host-key-md
1974 · stream-piece-selector
1976 · timeout
1978 · uri-selector
1980 · use-head
1982 · user-agent
1984 These options have exactly same meaning of the ones in the command-line
1986 options, but it just applies to the URIs it belongs to. Please note
1987 that for options in input file -- prefix must be stripped.
1988 For example, the content of uri.txt is:
1990 http://server/file.iso http://mirror/file.iso
1992 dir=/iso_images
1993 out=file.img
1994 http://foo/bar
1995 If aria2 is executed with -i uri.txt -d /tmp options, then file.iso is
1997 saved as /iso_images/file.img and it is downloaded from
1998 http://server/file.iso and http://mirror/file.iso. The file bar is
1999 downloaded from http://foo/bar and saved as /tmp/bar.
2000 In some cases, out parameter has no effect. See note of --out option
2002 for the restrictions.
2003 Server Performance Profile
2005 This section describes the format of server performance profile. The
2006 file is plain text and each line has several NAME=VALUE pair, delimited
2007 by comma. Currently following NAMEs are recognized:
2008 host Host name of the server. Required.
2010 protocol
2012 Protocol for this profile, such as ftp, http. Required.
2013 dl_speed
2015 The average download speed observed in the previous download in
2016 bytes per sec. Required.
2017 sc_avg_speed
2019 The average download speed observed in the previous download in
2020 bytes per sec. This value is only updated if the download is
2021 done in single connection environment and only used by Adap‐
2022 tiveURISelector. Optional.
2023 mc_avg_speed
2025 The average download speed observed in the previous download in
2026 bytes per sec. This value is only updated if the download is
2027 done in multi connection environment and only used by Adap‐
2028 tiveURISelector. Optional.
2029 counter
2031 How many times the server is used. Currently this value is only
2032 used by AdaptiveURISelector. Optional.
2033 last_updated
2035 Last contact time in GMT with this server, specified in the sec‐
2036 onds since the Epoch(00:00:00 on January 1, 1970, UTC).
2037 Required.
2038 status ERROR is set when server cannot be reached or out-of-service or
2040 timeout occurred. Otherwise, OK is set.
2041 Those fields must exist in one line. The order of the fields is not
2043 significant. You can put pairs other than the above; they are simply
2044 ignored.
2045 An example follows:
2047 host=localhost, protocol=http, dl_speed=32000, last_updated=1222491640, status=OK
2049 host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR
2050
2052 aria2 provides JSON-RPC over HTTP and XML-RPC over HTTP interfaces that
2053 offer basically the same functionality. aria2 also provides JSON-RPC
2054 over WebSocket. JSON-RPC over WebSocket uses the same method signatures
2055 and response format as JSON-RPC over HTTP, but additionally provides
2056 server-initiated notifications. See JSON-RPC over WebSocket section for
2057 more information.
2058 The request path of the JSON-RPC interface (for both over HTTP and over
2060 WebSocket) is /jsonrpc. The request path of the XML-RPC interface is
2061 /rpc.
2062 The WebSocket URI for JSON-RPC over WebSocket is ws://HOST:PORT/json‐
2064 rpc. If you enabled SSL/TLS encryption, use wss://HOST:PORT/jsonrpc
2065 instead.
2066 The implemented JSON-RPC is based on JSON-RPC 2.0 <‐
2068 http://jsonrpc.org/specification>, and supports HTTP POST and GET
2069 (JSONP). The WebSocket transport is an aria2 extension.
2070 The JSON-RPC interface does not support notifications over HTTP, but
2072 the RPC server will send notifications over WebSocket. It also does not
2073 support floating point numbers. The character encoding must be UTF-8.
2074 When reading the following documentation for JSON-RPC, interpret
2076 structs as JSON objects.
2077 Terminology
2079 GID
2080 The GID (or gid) is a key to manage each download. Each download
2081 will be assigned a unique GID. The GID is stored as 64-bit binary
2082 value in aria2. For RPC access, it is represented as a hex string
2083 of 16 characters (e.g., 2089b05ecca3d829). Normally, aria2 generates
2084 this GID for each download, but the user can specify GIDs manually
2085 using the --gid option. When querying downloads by GID, you can
2086 specify only the prefix of a GID as long as it is unique among oth‐
2087 ers.
2088 RPC authorization secret token
2090 As of 1.18.4, in addition to HTTP basic authorization, aria2 provides
2091 RPC method-level authorization. In a future release, HTTP basic autho‐
2092 rization will be removed and RPC method-level authorization will become
2093 mandatory.
2094 To use RPC method-level authorization, the user has to specify an RPC
2096 secret authorization token using the --rpc-secret option. For each RPC
2097 method call, the caller has to include the token prefixed with token:.
2098 Even when the --rpc-secret option is not used, if the first parameter
2099 in the RPC method is a string and starts with token:, it will removed
2100 from the parameter list before the request is being processed.
2101 For example, if the RPC secret authorization token is $$secret$$, call‐
2103 ing aria2.addUri RPC method would have to look like this:
2104 aria2.addUri("token:$$secret$$", ["http://example.org/file"])
2106 The system.multicall RPC method is treated specially. Since the XML-RPC
2108 specification only allows a single array as a parameter for this
2109 method, we don't specify the token in the call. Instead, each nested
2110 method call has to provide the token as the first parameter as
2111 described above.
2112 NOTE:
2114 The secret token validation in aria2 is designed to take at least a
2115 certain amount of time to mitigate brute-force/dictionary attacks
2116 against the RPC interface. Therefore it is recommended to prefer
2117 Batch or system.multicall requests when appropriate.
2118 system.listMethods and system.listNotifications can be executed
2120 without token. Since they just return available methods/notifica‐
2121 tions, they do not alter anything, they're safe without secret
2122 token.
2123 Methods
2125 All code examples are compatible with the Python 2.7 interpreter. For
2126 information on the secret parameter, see RPC authorization secret
2127 token.
2128 aria2.addUri([secret], uris[, options[, position]])
2130 This method adds a new download. uris is an array of
2131 HTTP/FTP/SFTP/BitTorrent URIs (strings) pointing to the same
2132 resource. If you mix URIs pointing to different resources, then
2133 the download may fail or be corrupted without aria2 complaining.
2134 When adding BitTorrent Magnet URIs, uris must have only one ele‐
2135 ment and it should be BitTorrent Magnet URI. options is a
2136 struct and its members are pairs of option name and value. See
2137 Options below for more details. If position is given, it must
2138 be an integer starting from 0. The new download will be inserted
2139 at position in the waiting queue. If position is omitted or
2140 position is larger than the current size of the queue, the new
2141 download is appended to the end of the queue. This method
2142 returns the GID of the newly registered download.
2143 JSON-RPC Example
2145 The following example adds http://example.org/file:
2147 >>> import urllib2, json
2149 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2150 ... 'method':'aria2.addUri',
2151 ... 'params':[['http://example.org/file']]})
2152 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2153 >>> c.read()
2154 '{"id":"qwer","jsonrpc":"2.0","result":"2089b05ecca3d829"}'
2155 XML-RPC Example
2157 The following example adds http://example.org/file:
2159 >>> import xmlrpclib
2161 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2162 >>> s.aria2.addUri(['http://example.org/file'])
2163 '2089b05ecca3d829'
2164 The following example adds a new download with two sources and
2166 some options:
2167 >>> s.aria2.addUri(['http://example.org/file', 'http://mirror/file'],
2169 dict(dir="/tmp"))
2170 'd2703803b52216d1'
2171 The following example adds a download and inserts it to the
2173 front of the queue:
2174 >>> s.aria2.addUri(['http://example.org/file'], {}, 0)
2176 'ca3d829cee549a4d'
2177 aria2.addTorrent([secret], torrent[, uris[, options[, position]]])
2179 This method adds a BitTorrent download by uploading a ".torrent"
2180 file. If you want to add a BitTorrent Magnet URI, use the
2181 aria2.addUri() method instead. torrent must be a base64-encoded
2182 string containing the contents of the ".torrent" file. uris is
2183 an array of URIs (string). uris is used for Web-seeding. For
2184 single file torrents, the URI can be a complete URI pointing to
2185 the resource; if URI ends with /, name in torrent file is added.
2186 For multi-file torrents, name and path in torrent are added to
2187 form a URI for each file. options is a struct and its members
2188 are pairs of option name and value. See Options below for more
2189 details. If position is given, it must be an integer starting
2190 from 0. The new download will be inserted at position in the
2191 waiting queue. If position is omitted or position is larger than
2192 the current size of the queue, the new download is appended to
2193 the end of the queue. This method returns the GID of the newly
2194 registered download. If --rpc-save-upload-metadata is true, the
2195 uploaded data is saved as a file named as the hex string of
2196 SHA-1 hash of data plus ".torrent" in the directory specified by
2197 --dir option. E.g. a file name might be
2198 0a3893293e27ac0490424c06de4d09242215f0a6.torrent. If a file
2199 with the same name already exists, it is overwritten! If the
2200 file cannot be saved successfully or --rpc-save-upload-metadata
2201 is false, the downloads added by this method are not saved by
2202 --save-session.
2203 The following examples add local file file.torrent.
2205 JSON-RPC Example
2207 >>> import urllib2, json, base64
2209 >>> torrent = base64.b64encode(open('file.torrent').read())
2210 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'asdf',
2211 ... 'method':'aria2.addTorrent', 'params':[torrent]})
2212 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2213 >>> c.read()
2214 '{"id":"asdf","jsonrpc":"2.0","result":"2089b05ecca3d829"}'
2215 XML-RPC Example
2217 >>> import xmlrpclib
2219 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2220 >>> s.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent', mode='rb').read()))
2221 '2089b05ecca3d829'
2222 aria2.addMetalink([secret], metalink[, options[, position]])
2224 This method adds a Metalink download by uploading a ".metalink"
2225 file. metalink is a base64-encoded string which contains the
2226 contents of the ".metalink" file. options is a struct and its
2227 members are pairs of option name and value. See Options below
2228 for more details. If position is given, it must be an integer
2229 starting from 0. The new download will be inserted at position
2230 in the waiting queue. If position is omitted or position is
2231 larger than the current size of the queue, the new download is
2232 appended to the end of the queue. This method returns an array
2233 of GIDs of newly registered downloads. If
2234 --rpc-save-upload-metadata is true, the uploaded data is saved
2235 as a file named hex string of SHA-1 hash of data plus ".met‐
2236 alink" in the directory specified by --dir option. E.g. a file
2237 name might be 0a3893293e27ac0490424c06de4d09242215f0a6.metalink.
2238 If a file with the same name already exists, it is overwritten!
2239 If the file cannot be saved successfully or
2240 --rpc-save-upload-metadata is false, the downloads added by this
2241 method are not saved by --save-session.
2242 The following examples add local file file.meta4.
2244 JSON-RPC Example
2246 >>> import urllib2, json, base64
2248 >>> metalink = base64.b64encode(open('file.meta4').read())
2249 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2250 ... 'method':'aria2.addMetalink',
2251 ... 'params':[metalink]})
2252 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2253 >>> c.read()
2254 '{"id":"qwer","jsonrpc":"2.0","result":["2089b05ecca3d829"]}'
2255 XML-RPC Example
2257 >>> import xmlrpclib
2259 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2260 >>> s.aria2.addMetalink(xmlrpclib.Binary(open('file.meta4', mode='rb').read()))
2261 ['2089b05ecca3d829']
2262 aria2.remove([secret], gid)
2264 This method removes the download denoted by gid (string). If
2265 the specified download is in progress, it is first stopped. The
2266 status of the removed download becomes removed. This method
2267 returns GID of removed download.
2268 The following examples remove a download with
2270 GID#2089b05ecca3d829.
2271 JSON-RPC Example
2273 >>> import urllib2, json
2275 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2276 ... 'method':'aria2.remove',
2277 ... 'params':['2089b05ecca3d829']})
2278 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2279 >>> c.read()
2280 '{"id":"qwer","jsonrpc":"2.0","result":"2089b05ecca3d829"}'
2281 XML-RPC Example
2283 >>> import xmlrpclib
2285 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2286 >>> s.aria2.remove('2089b05ecca3d829')
2287 '2089b05ecca3d829'
2288 aria2.forceRemove([secret], gid)
2290 This method removes the download denoted by gid. This method
2291 behaves just like aria2.remove() except that this method removes
2292 the download without performing any actions which take time,
2293 such as contacting BitTorrent trackers to unregister the down‐
2294 load first.
2295 aria2.pause([secret], gid)
2297 This method pauses the download denoted by gid (string). The
2298 status of paused download becomes paused. If the download was
2299 active, the download is placed in the front of waiting queue.
2300 While the status is paused, the download is not started. To
2301 change status to waiting, use the aria2.unpause() method. This
2302 method returns GID of paused download.
2303 aria2.pauseAll([secret])
2305 This method is equal to calling aria2.pause() for every
2306 active/waiting download. This methods returns OK.
2307 aria2.forcePause([secret], gid)
2309 This method pauses the download denoted by gid. This method
2310 behaves just like aria2.pause() except that this method pauses
2311 downloads without performing any actions which take time, such
2312 as contacting BitTorrent trackers to unregister the download
2313 first.
2314 aria2.forcePauseAll([secret])
2316 This method is equal to calling aria2.forcePause() for every
2317 active/waiting download. This methods returns OK.
2318 aria2.unpause([secret], gid)
2320 This method changes the status of the download denoted by gid
2321 (string) from paused to waiting, making the download eligible to
2322 be restarted. This method returns the GID of the unpaused down‐
2323 load.
2324 aria2.unpauseAll([secret])
2326 This method is equal to calling aria2.unpause() for every paused
2327 download. This methods returns OK.
2328 aria2.tellStatus([secret], gid[, keys])
2330 This method returns the progress of the download denoted by gid
2331 (string). keys is an array of strings. If specified, the
2332 response contains only keys in the keys array. If keys is empty
2333 or omitted, the response contains all keys. This is useful when
2334 you just want specific keys and avoid unnecessary transfers.
2335 For example, aria2.tellStatus("2089b05ecca3d829", ["gid", "sta‐
2336 tus"]) returns the gid and status keys only. The response is a
2337 struct and contains following keys. Values are strings.
2338 gid GID of the download.
2340 status active for currently downloading/seeding downloads.
2342 waiting for downloads in the queue; download is not
2343 started. paused for paused downloads. error for down‐
2344 loads that were stopped because of error. complete for
2345 stopped and completed downloads. removed for the down‐
2346 loads removed by user.
2347 totalLength
2349 Total length of the download in bytes.
2350 completedLength
2352 Completed length of the download in bytes.
2353 uploadLength
2355 Uploaded length of the download in bytes.
2356 bitfield
2358 Hexadecimal representation of the download progress. The
2359 highest bit corresponds to the piece at index 0. Any set
2360 bits indicate loaded pieces, while unset bits indicate
2361 not yet loaded and/or missing pieces. Any overflow bits
2362 at the end are set to zero. When the download was not
2363 started yet, this key will not be included in the
2364 response.
2365 downloadSpeed
2367 Download speed of this download measured in bytes/sec.
2368 uploadSpeed
2370 Upload speed of this download measured in bytes/sec.
2371 infoHash
2373 InfoHash. BitTorrent only.
2374 numSeeders
2376 The number of seeders aria2 has connected to. BitTorrent
2377 only.
2378 seeder true if the local endpoint is a seeder. Otherwise false.
2380 BitTorrent only.
2381 pieceLength
2383 Piece length in bytes.
2384 numPieces
2386 The number of pieces.
2387 connections
2389 The number of peers/servers aria2 has connected to.
2390 errorCode
2392 The code of the last error for this item, if any. The
2393 value is a string. The error codes are defined in the
2394 EXIT STATUS section. This value is only available for
2395 stopped/completed downloads.
2396 errorMessage
2398 The (hopefully) human readable error message associated
2399 to errorCode.
2400 followedBy
2402 List of GIDs which are generated as the result of this
2403 download. For example, when aria2 downloads a Metalink
2404 file, it generates downloads described in the Metalink
2405 (see the --follow-metalink option). This value is useful
2406 to track auto-generated downloads. If there are no such
2407 downloads, this key will not be included in the response.
2408 following
2410 The reverse link for followedBy. A download included in
2411 followedBy has this object's GID in its following value.
2412 belongsTo
2414 GID of a parent download. Some downloads are a part of
2415 another download. For example, if a file in a Metalink
2416 has BitTorrent resources, the downloads of ".torrent"
2417 files are parts of that parent. If this download has no
2418 parent, this key will not be included in the response.
2419 dir Directory to save files.
2421 files Returns the list of files. The elements of this list are
2423 the same structs used in aria2.getFiles() method.
2424 bittorrent
2426 Struct which contains information retrieved from the
2427 .torrent (file). BitTorrent only. It contains following
2428 keys.
2429 announceList
2431 List of lists of announce URIs. If the torrent
2432 contains announce and no announce-list, announce
2433 is converted to the announce-list format.
2434 comment
2436 The comment of the torrent. comment.utf-8 is used
2437 if available.
2438 creationDate
2440 The creation time of the torrent. The value is an
2441 integer since the epoch, measured in seconds.
2442 mode File mode of the torrent. The value is either sin‐
2444 gle or multi.
2445 info Struct which contains data from Info dictionary.
2447 It contains following keys.
2448 name name in info dictionary. name.utf-8 is used
2450 if available.
2451 verifiedLength
2453 The number of verified number of bytes while the files
2454 are being hash checked. This key exists only when this
2455 download is being hash checked.
2456 verifyIntegrityPending
2458 true if this download is waiting for the hash check in a
2459 queue. This key exists only when this download is in the
2460 queue.
2461 JSON-RPC Example
2463 The following example gets information about a download with
2465 GID#2089b05ecca3d829:
2466 >>> import urllib2, json
2468 >>> from pprint import pprint
2469 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2470 ... 'method':'aria2.tellStatus',
2471 ... 'params':['2089b05ecca3d829']})
2472 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2473 >>> pprint(json.loads(c.read()))
2474 {u'id': u'qwer',
2475 u'jsonrpc': u'2.0',
2476 u'result': {u'bitfield': u'0000000000',
2477 u'completedLength': u'901120',
2478 u'connections': u'1',
2479 u'dir': u'/downloads',
2480 u'downloadSpeed': u'15158',
2481 u'files': [{u'index': u'1',
2482 u'length': u'34896138',
2483 u'completedLength': u'34896138',
2484 u'path': u'/downloads/file',
2485 u'selected': u'true',
2486 u'uris': [{u'status': u'used',
2487 u'uri': u'http://example.org/file'}]}],
2488 u'gid': u'2089b05ecca3d829',
2489 u'numPieces': u'34',
2490 u'pieceLength': u'1048576',
2491 u'status': u'active',
2492 u'totalLength': u'34896138',
2493 u'uploadLength': u'0',
2494 u'uploadSpeed': u'0'}}
2495 The following example gets only specific keys:
2497 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2499 ... 'method':'aria2.tellStatus',
2500 ... 'params':['2089b05ecca3d829',
2501 ... ['gid',
2502 ... 'totalLength',
2503 ... 'completedLength']]})
2504 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2505 >>> pprint(json.loads(c.read()))
2506 {u'id': u'qwer',
2507 u'jsonrpc': u'2.0',
2508 u'result': {u'completedLength': u'5701632',
2509 u'gid': u'2089b05ecca3d829',
2510 u'totalLength': u'34896138'}}
2511 XML-RPC Example
2513 The following example gets information about a download with
2515 GID#2089b05ecca3d829:
2516 >>> import xmlrpclib
2518 >>> from pprint import pprint
2519 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2520 >>> r = s.aria2.tellStatus('2089b05ecca3d829')
2521 >>> pprint(r)
2522 {'bitfield': 'ffff80',
2523 'completedLength': '34896138',
2524 'connections': '0',
2525 'dir': '/downloads',
2526 'downloadSpeed': '0',
2527 'errorCode': '0',
2528 'files': [{'index': '1',
2529 'length': '34896138',
2530 'completedLength': '34896138',
2531 'path': '/downloads/file',
2532 'selected': 'true',
2533 'uris': [{'status': 'used',
2534 'uri': 'http://example.org/file'}]}],
2535 'gid': '2089b05ecca3d829',
2536 'numPieces': '17',
2537 'pieceLength': '2097152',
2538 'status': 'complete',
2539 'totalLength': '34896138',
2540 'uploadLength': '0',
2541 'uploadSpeed': '0'}
2542 The following example gets only specific keys:
2544 >>> r = s.aria2.tellStatus('2089b05ecca3d829', ['gid', 'totalLength', 'completedLength'])
2546 >>> pprint(r)
2547 {'completedLength': '34896138', 'gid': '2089b05ecca3d829', 'totalLength': '34896138'}
2548 aria2.getUris([secret], gid)
2550 This method returns the URIs used in the download denoted by gid
2551 (string). The response is an array of structs and it contains
2552 following keys. Values are string.
2553 uri URI
2555 status 'used' if the URI is in use. 'waiting' if the URI is
2557 still waiting in the queue.
2558 JSON-RPC Example
2560 >>> import urllib2, json
2562 >>> from pprint import pprint
2563 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2564 ... 'method':'aria2.getUris',
2565 ... 'params':['2089b05ecca3d829']})
2566 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2567 >>> pprint(json.loads(c.read()))
2568 {u'id': u'qwer',
2569 u'jsonrpc': u'2.0',
2570 u'result': [{u'status': u'used',
2571 u'uri': u'http://example.org/file'}]}
2572 XML-RPC Example
2574 >>> import xmlrpclib
2576 >>> from pprint import pprint
2577 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2578 >>> r = s.aria2.getUris('2089b05ecca3d829')
2579 >>> pprint(r)
2580 [{'status': 'used', 'uri': 'http://example.org/file'}]
2581 aria2.getFiles([secret], gid)
2583 This method returns the file list of the download denoted by gid
2584 (string). The response is an array of structs which contain
2585 following keys. Values are strings.
2586 index Index of the file, starting at 1, in the same order as
2588 files appear in the multi-file torrent.
2589 path File path.
2591 length File size in bytes.
2593 completedLength
2595 Completed length of this file in bytes. Please note that
2596 it is possible that sum of completedLength is less than
2597 the completedLength returned by the aria2.tellStatus()
2598 method. This is because completedLength in
2599 aria2.getFiles() only includes completed pieces. On the
2600 other hand, completedLength in aria2.tellStatus() also
2601 includes partially completed pieces.
2602 selected
2604 true if this file is selected by --select-file option. If
2605 --select-file is not specified or this is single-file
2606 torrent or not a torrent download at all, this value is
2607 always true. Otherwise false.
2608 uris Returns a list of URIs for this file. The element type is
2610 the same struct used in the aria2.getUris() method.
2611 JSON-RPC Example
2613 >>> import urllib2, json
2615 >>> from pprint import pprint
2616 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2617 ... 'method':'aria2.getFiles',
2618 ... 'params':['2089b05ecca3d829']})
2619 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2620 >>> pprint(json.loads(c.read()))
2621 {u'id': u'qwer',
2622 u'jsonrpc': u'2.0',
2623 u'result': [{u'index': u'1',
2624 u'length': u'34896138',
2625 u'completedLength': u'34896138',
2626 u'path': u'/downloads/file',
2627 u'selected': u'true',
2628 u'uris': [{u'status': u'used',
2629 u'uri': u'http://example.org/file'}]}]}
2630 XML-RPC Example
2632 >>> import xmlrpclib
2634 >>> from pprint import pprint
2635 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2636 >>> r = s.aria2.getFiles('2089b05ecca3d829')
2637 >>> pprint(r)
2638 [{'index': '1',
2639 'length': '34896138',
2640 'completedLength': '34896138',
2641 'path': '/downloads/file',
2642 'selected': 'true',
2643 'uris': [{'status': 'used',
2644 'uri': 'http://example.org/file'}]}]
2645 aria2.getPeers([secret], gid)
2647 This method returns a list peers of the download denoted by gid
2648 (string). This method is for BitTorrent only. The response is
2649 an array of structs and contains the following keys. Values are
2650 strings.
2651 peerId Percent-encoded peer ID.
2653 ip IP address of the peer.
2655 port Port number of the peer.
2657 bitfield
2659 Hexadecimal representation of the download progress of
2660 the peer. The highest bit corresponds to the piece at
2661 index 0. Set bits indicate the piece is available and
2662 unset bits indicate the piece is missing. Any spare bits
2663 at the end are set to zero.
2664 amChoking
2666 true if aria2 is choking the peer. Otherwise false.
2667 peerChoking
2669 true if the peer is choking aria2. Otherwise false.
2670 downloadSpeed
2672 Download speed (byte/sec) that this client obtains from
2673 the peer.
2674 uploadSpeed
2676 Upload speed(byte/sec) that this client uploads to the
2677 peer.
2678 seeder true if this peer is a seeder. Otherwise false.
2680 JSON-RPC Example
2682 >>> import urllib2, json
2684 >>> from pprint import pprint
2685 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2686 ... 'method':'aria2.getPeers',
2687 ... 'params':['2089b05ecca3d829']})
2688 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2689 >>> pprint(json.loads(c.read()))
2690 {u'id': u'qwer',
2691 u'jsonrpc': u'2.0',
2692 u'result': [{u'amChoking': u'true',
2693 u'bitfield': u'ffffffffffffffffffffffffffffffffffffffff',
2694 u'downloadSpeed': u'10602',
2695 u'ip': u'10.0.0.9',
2696 u'peerChoking': u'false',
2697 u'peerId': u'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6',
2698 u'port': u'6881',
2699 u'seeder': u'true',
2700 u'uploadSpeed': u'0'},
2701 {u'amChoking': u'false',
2702 u'bitfield': u'ffffeff0fffffffbfffffff9fffffcfff7f4ffff',
2703 u'downloadSpeed': u'8654',
2704 u'ip': u'10.0.0.30',
2705 u'peerChoking': u'false',
2706 u'peerId': u'bittorrent client758',
2707 u'port': u'37842',
2708 u'seeder': u'false',
2709 u'uploadSpeed': u'6890'}]}
2710 XML-RPC Example
2712 >>> import xmlrpclib
2714 >>> from pprint import pprint
2715 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2716 >>> r = s.aria2.getPeers('2089b05ecca3d829')
2717 >>> pprint(r)
2718 [{'amChoking': 'true',
2719 'bitfield': 'ffffffffffffffffffffffffffffffffffffffff',
2720 'downloadSpeed': '10602',
2721 'ip': '10.0.0.9',
2722 'peerChoking': 'false',
2723 'peerId': 'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6',
2724 'port': '6881',
2725 'seeder': 'true',
2726 'uploadSpeed': '0'},
2727 {'amChoking': 'false',
2728 'bitfield': 'ffffeff0fffffffbfffffff9fffffcfff7f4ffff',
2729 'downloadSpeed': '8654',
2730 'ip': '10.0.0.30',
2731 'peerChoking': 'false',
2732 'peerId': 'bittorrent client758',
2733 'port': '37842',
2734 'seeder': 'false,
2735 'uploadSpeed': '6890'}]
2736 aria2.getServers([secret], gid)
2738 This method returns currently connected HTTP(S)/FTP/SFTP servers
2739 of the download denoted by gid (string). The response is an
2740 array of structs and contains the following keys. Values are
2741 strings.
2742 index Index of the file, starting at 1, in the same order as
2744 files appear in the multi-file metalink.
2745 servers
2747 A list of structs which contain the following keys.
2748 uri Original URI.
2750 currentUri
2752 This is the URI currently used for downloading. If
2753 redirection is involved, currentUri and uri may
2754 differ.
2755 downloadSpeed
2757 Download speed (byte/sec)
2758 JSON-RPC Example
2760 >>> import urllib2, json
2762 >>> from pprint import pprint
2763 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2764 ... 'method':'aria2.getServers',
2765 ... 'params':['2089b05ecca3d829']})
2766 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2767 >>> pprint(json.loads(c.read()))
2768 {u'id': u'qwer',
2769 u'jsonrpc': u'2.0',
2770 u'result': [{u'index': u'1',
2771 u'servers': [{u'currentUri': u'http://example.org/file',
2772 u'downloadSpeed': u'10467',
2773 u'uri': u'http://example.org/file'}]}]}
2774 XML-RPC Example
2776 >>> import xmlrpclib
2778 >>> from pprint import pprint
2779 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2780 >>> r = s.aria2.getServers('2089b05ecca3d829')
2781 >>> pprint(r)
2782 [{'index': '1',
2783 'servers': [{'currentUri': 'http://example.org/dl/file',
2784 'downloadSpeed': '20285',
2785 'uri': 'http://example.org/file'}]}]
2786 aria2.tellActive([secret][, keys])
2788 This method returns a list of active downloads. The response is
2789 an array of the same structs as returned by the
2790 aria2.tellStatus() method. For the keys parameter, please refer
2791 to the aria2.tellStatus() method.
2792 aria2.tellWaiting([secret], offset, num[, keys])
2794 This method returns a list of waiting downloads, including
2795 paused ones. offset is an integer and specifies the offset from
2796 the download waiting at the front. num is an integer and speci‐
2797 fies the max. number of downloads to be returned. For the keys
2798 parameter, please refer to the aria2.tellStatus() method.
2799 If offset is a positive integer, this method returns downloads
2801 in the range of [offset, offset + num).
2802 offset can be a negative integer. offset == -1 points last down‐
2804 load in the waiting queue and offset == -2 points the download
2805 before the last download, and so on. Downloads in the response
2806 are in reversed order then.
2807 For example, imagine three downloads "A","B" and "C" are waiting
2809 in this order. aria2.tellWaiting(0, 1) returns ["A"].
2810 aria2.tellWaiting(1, 2) returns ["B", "C"]. aria2.tellWait‐
2811 ing(-1, 2) returns ["C", "B"].
2812 The response is an array of the same structs as returned by
2814 aria2.tellStatus() method.
2815 aria2.tellStopped([secret], offset, num[, keys])
2817 This method returns a list of stopped downloads. offset is an
2818 integer and specifies the offset from the least recently stopped
2819 download. num is an integer and specifies the max. number of
2820 downloads to be returned. For the keys parameter, please refer
2821 to the aria2.tellStatus() method.
2822 offset and num have the same semantics as described in the
2824 aria2.tellWaiting() method.
2825 The response is an array of the same structs as returned by the
2827 aria2.tellStatus() method.
2828 aria2.changePosition([secret], gid, pos, how)
2830 This method changes the position of the download denoted by gid
2831 in the queue. pos is an integer. how is a string. If how is
2832 POS_SET, it moves the download to a position relative to the
2833 beginning of the queue. If how is POS_CUR, it moves the down‐
2834 load to a position relative to the current position. If how is
2835 POS_END, it moves the download to a position relative to the end
2836 of the queue. If the destination position is less than 0 or
2837 beyond the end of the queue, it moves the download to the begin‐
2838 ning or the end of the queue respectively. The response is an
2839 integer denoting the resulting position.
2840 For example, if GID#2089b05ecca3d829 is currently in position 3,
2842 aria2.changePosition('2089b05ecca3d829', -1, 'POS_CUR') will
2843 change its position to 2. Additionally aria2.changePosi‐
2844 tion('2089b05ecca3d829', 0, 'POS_SET') will change its position
2845 to 0 (the beginning of the queue).
2846 The following examples move the download GID#2089b05ecca3d829 to
2848 the front of the queue.
2849 JSON-RPC Example
2851 >>> import urllib2, json
2853 >>> from pprint import pprint
2854 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2855 ... 'method':'aria2.changePosition',
2856 ... 'params':['2089b05ecca3d829', 0, 'POS_SET']})
2857 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2858 >>> pprint(json.loads(c.read()))
2859 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': 0}
2860 XML-RPC Example
2862 >>> import xmlrpclib
2864 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2865 >>> s.aria2.changePosition('2089b05ecca3d829', 0, 'POS_SET')
2866 0
2867 aria2.changeUri([secret], gid, fileIndex, delUris, addUris[, position])
2869 This method removes the URIs in delUris from and appends the
2870 URIs in addUris to download denoted by gid. delUris and addUris
2871 are lists of strings. A download can contain multiple files and
2872 URIs are attached to each file. fileIndex is used to select
2873 which file to remove/attach given URIs. fileIndex is 1-based.
2874 position is used to specify where URIs are inserted in the
2875 existing waiting URI list. position is 0-based. When position is
2876 omitted, URIs are appended to the back of the list. This method
2877 first executes the removal and then the addition. position is
2878 the position after URIs are removed, not the position when this
2879 method is called. When removing an URI, if the same URIs exist
2880 in download, only one of them is removed for each URI in
2881 delUris. In other words, if there are three URIs http://exam‐
2882 ple.org/aria2 and you want remove them all, you have to specify
2883 (at least) 3 http://example.org/aria2 in delUris. This method
2884 returns a list which contains two integers. The first integer is
2885 the number of URIs deleted. The second integer is the number of
2886 URIs added.
2887 The following examples add the URI http://example.org/file to
2889 the file whose index is 1 and belongs to the download
2890 GID#2089b05ecca3d829.
2891 JSON-RPC Example
2893 >>> import urllib2, json
2895 >>> from pprint import pprint
2896 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2897 ... 'method':'aria2.changeUri',
2898 ... 'params':['2089b05ecca3d829', 1, [],
2899 ['http://example.org/file']]})
2900 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2901 >>> pprint(json.loads(c.read()))
2902 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [0, 1]}
2903 XML-RPC Example
2905 >>> import xmlrpclib
2907 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2908 >>> s.aria2.changeUri('2089b05ecca3d829', 1, [],
2909 ['http://example.org/file'])
2910 [0, 1]
2911 aria2.getOption([secret], gid)
2913 This method returns options of the download denoted by gid. The
2914 response is a struct where keys are the names of options. The
2915 values are strings. Note that this method does not return
2916 options which have no default value and have not been set on the
2917 command-line, in configuration files or RPC methods.
2918 The following examples get options of the download
2920 GID#2089b05ecca3d829.
2921 JSON-RPC Example
2923 >>> import urllib2, json
2925 >>> from pprint import pprint
2926 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2927 ... 'method':'aria2.getOption',
2928 ... 'params':['2089b05ecca3d829']})
2929 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2930 >>> pprint(json.loads(c.read()))
2931 {u'id': u'qwer',
2932 u'jsonrpc': u'2.0',
2933 u'result': {u'allow-overwrite': u'false',
2934 u'allow-piece-length-change': u'false',
2935 u'always-resume': u'true',
2936 u'async-dns': u'true',
2937 ...
2938 XML-RPC Example
2940 >>> import xmlrpclib
2942 >>> from pprint import pprint
2943 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2944 >>> r = s.aria2.getOption('2089b05ecca3d829')
2945 >>> pprint(r)
2946 {'allow-overwrite': 'false',
2947 'allow-piece-length-change': 'false',
2948 'always-resume': 'true',
2949 'async-dns': 'true',
2950 ....
2951 aria2.changeOption([secret], gid, options)
2953 This method changes options of the download denoted by gid
2954 (string) dynamically. options is a struct. The options listed
2955 in Input File subsection are available, except for following
2956 options:
2957 · dry-run
2959 · metalink-base-uri
2961 · parameterized-uri
2963 · pause
2965 · piece-length
2967 · rpc-save-upload-metadata
2969 Except for the following options, changing the other options of
2971 active download makes it restart (restart itself is managed by
2972 aria2, and no user intervention is required):
2973 · bt-max-peers
2975 · bt-request-peer-speed-limit
2977 · bt-remove-unselected-file
2979 · force-save
2981 · max-download-limit
2983 · max-upload-limit
2985 This method returns OK for success.
2987 The following examples set the max-download-limit option to 20K
2989 for the download GID#2089b05ecca3d829.
2990 JSON-RPC Example
2992 >>> import urllib2, json
2994 >>> from pprint import pprint
2995 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2996 ... 'method':'aria2.changeOption',
2997 ... 'params':['2089b05ecca3d829',
2998 ... {'max-download-limit':'10K'}]})
2999 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3000 >>> pprint(json.loads(c.read()))
3001 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'}
3002 XML-RPC Example
3004 >>> import xmlrpclib
3006 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3007 >>> s.aria2.changeOption('2089b05ecca3d829', {'max-download-limit':'20K'})
3008 'OK'
3009 aria2.getGlobalOption([secret])
3011 This method returns the global options. The response is a
3012 struct. Its keys are the names of options. Values are strings.
3013 Note that this method does not return options which have no
3014 default value and have not been set on the command-line, in con‐
3015 figuration files or RPC methods. Because global options are used
3016 as a template for the options of newly added downloads, the
3017 response contains keys returned by the aria2.getOption() method.
3018 aria2.changeGlobalOption([secret], options)
3020 This method changes global options dynamically. options is a
3021 struct. The following options are available:
3022 · bt-max-open-files
3024 · download-result
3026 · keep-unfinished-download-result
3028 · log
3030 · log-level
3032 · max-concurrent-downloads
3034 · max-download-result
3036 · max-overall-download-limit
3038 · max-overall-upload-limit
3040 · optimize-concurrent-downloads
3042 · save-cookies
3044 · save-session
3046 · server-stat-of
3048 In addition, options listed in the Input File subsection are
3050 available, except for following options: checksum, index-out,
3051 out, pause and select-file.
3052 With the log option, you can dynamically start logging or change
3054 log file. To stop logging, specify an empty string("") as the
3055 parameter value. Note that log file is always opened in append
3056 mode. This method returns OK for success.
3057 aria2.getGlobalStat([secret])
3059 This method returns global statistics such as the overall down‐
3060 load and upload speeds. The response is a struct and contains
3061 the following keys. Values are strings.
3062 downloadSpeed
3064 Overall download speed (byte/sec).
3065 uploadSpeed
3067 Overall upload speed(byte/sec).
3068 numActive
3070 The number of active downloads.
3071 numWaiting
3073 The number of waiting downloads.
3074 numStopped
3076 The number of stopped downloads in the current session.
3077 This value is capped by the --max-download-result option.
3078 numStoppedTotal
3080 The number of stopped downloads in the current session
3081 and not capped by the --max-download-result option.
3082 JSON-RPC Example
3084 >>> import urllib2, json
3086 >>> from pprint import pprint
3087 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3088 ... 'method':'aria2.getGlobalStat'})
3089 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3090 >>> pprint(json.loads(c.read()))
3091 {u'id': u'qwer',
3092 u'jsonrpc': u'2.0',
3093 u'result': {u'downloadSpeed': u'21846',
3094 u'numActive': u'2',
3095 u'numStopped': u'0',
3096 u'numWaiting': u'0',
3097 u'uploadSpeed': u'0'}}
3098 XML-RPC Example
3100 >>> import xmlrpclib
3102 >>> from pprint import pprint
3103 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3104 >>> r = s.aria2.getGlobalStat()
3105 >>> pprint(r)
3106 {'downloadSpeed': '23136',
3107 'numActive': '2',
3108 'numStopped': '0',
3109 'numWaiting': '0',
3110 'uploadSpeed': '0'}
3111 aria2.purgeDownloadResult([secret])
3113 This method purges completed/error/removed downloads to free
3114 memory. This method returns OK.
3115 aria2.removeDownloadResult([secret], gid)
3117 This method removes a completed/error/removed download denoted
3118 by gid from memory. This method returns OK for success.
3119 The following examples remove the download result of the down‐
3121 load GID#2089b05ecca3d829.
3122 JSON-RPC Example
3124 >>> import urllib2, json
3126 >>> from pprint import pprint
3127 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3128 ... 'method':'aria2.removeDownloadResult',
3129 ... 'params':['2089b05ecca3d829']})
3130 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3131 >>> pprint(json.loads(c.read()))
3132 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'}
3133 XML-RPC Example
3135 >>> import xmlrpclib
3137 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3138 >>> s.aria2.removeDownloadResult('2089b05ecca3d829')
3139 'OK'
3140 aria2.getVersion([secret])
3142 This method returns the version of aria2 and the list of enabled
3143 features. The response is a struct and contains following keys.
3144 version
3146 Version number of aria2 as a string.
3147 enabledFeatures
3149 List of enabled features. Each feature is given as a
3150 string.
3151 JSON-RPC Example
3153 >>> import urllib2, json
3155 >>> from pprint import pprint
3156 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3157 ... 'method':'aria2.getVersion'})
3158 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3159 >>> pprint(json.loads(c.read()))
3160 {u'id': u'qwer',
3161 u'jsonrpc': u'2.0',
3162 u'result': {u'enabledFeatures': [u'Async DNS',
3163 u'BitTorrent',
3164 u'Firefox3 Cookie',
3165 u'GZip',
3166 u'HTTPS',
3167 u'Message Digest',
3168 u'Metalink',
3169 u'XML-RPC'],
3170 u'version': u'1.11.0'}}
3171 XML-RPC Example
3173 >>> import xmlrpclib
3175 >>> from pprint import pprint
3176 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3177 >>> r = s.aria2.getVersion()
3178 >>> pprint(r)
3179 {'enabledFeatures': ['Async DNS',
3180 'BitTorrent',
3181 'Firefox3 Cookie',
3182 'GZip',
3183 'HTTPS',
3184 'Message Digest',
3185 'Metalink',
3186 'XML-RPC'],
3187 'version': '1.11.0'}
3188 aria2.getSessionInfo([secret])
3190 This method returns session information. The response is a
3191 struct and contains following key.
3192 sessionId
3194 Session ID, which is generated each time when aria2 is
3195 invoked.
3196 JSON-RPC Example
3198 >>> import urllib2, json
3200 >>> from pprint import pprint
3201 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3202 ... 'method':'aria2.getSessionInfo'})
3203 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3204 >>> pprint(json.loads(c.read()))
3205 {u'id': u'qwer',
3206 u'jsonrpc': u'2.0',
3207 u'result': {u'sessionId': u'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}}
3208 XML-RPC Example
3210 >>> import xmlrpclib
3212 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3213 >>> s.aria2.getSessionInfo()
3214 {'sessionId': 'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}
3215 aria2.shutdown([secret])
3217 This method shuts down aria2. This method returns OK.
3218 aria2.forceShutdown([secret])
3220 This method shuts down aria2(). This method behaves like
3221 :func:'aria2.shutdown` without performing any actions which take
3222 time, such as contacting BitTorrent trackers to unregister down‐
3223 loads first. This method returns OK.
3224 aria2.saveSession([secret])
3226 This method saves the current session to a file specified by the
3227 --save-session option. This method returns OK if it succeeds.
3228 system.multicall(methods)
3230 This methods encapsulates multiple method calls in a single
3231 request. methods is an array of structs. The structs contain
3232 two keys: methodName and params. methodName is the method name
3233 to call and params is array containing parameters to the method
3234 call. This method returns an array of responses. The elements
3235 will be either a one-item array containing the return value of
3236 the method call or a struct of fault element if an encapsulated
3237 method call fails.
3238 In the following examples, we add 2 downloads. The first one is
3240 http://example.org/file and the second one is file.torrent.
3241 JSON-RPC Example
3243 >>> import urllib2, json, base64
3245 >>> from pprint import pprint
3246 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3247 ... 'method':'system.multicall',
3248 ... 'params':[[{'methodName':'aria2.addUri',
3249 ... 'params':[['http://example.org']]},
3250 ... {'methodName':'aria2.addTorrent',
3251 ... 'params':[base64.b64encode(open('file.torrent').read())]}]]})
3252 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3253 >>> pprint(json.loads(c.read()))
3254 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [[u'2089b05ecca3d829'], [u'd2703803b52216d1']]}
3255 JSON-RPC additionally supports Batch requests as described in
3257 the JSON-RPC 2.0 Specification:
3258 >>> jsonreq = json.dumps([{'jsonrpc':'2.0', 'id':'qwer',
3260 ... 'method':'aria2.addUri',
3261 ... 'params':[['http://example.org']]},
3262 ... {'jsonrpc':'2.0', 'id':'asdf',
3263 ... 'method':'aria2.addTorrent',
3264 ... 'params':[base64.b64encode(open('file.torrent').read())]}])
3265 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3266 >>> pprint(json.loads(c.read()))
3267 [{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'2089b05ecca3d829'},
3268 {u'id': u'asdf', u'jsonrpc': u'2.0', u'result': u'd2703803b52216d1'}]
3269 XML-RPC Example
3271 >>> import xmlrpclib
3273 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3274 >>> mc = xmlrpclib.MultiCall(s)
3275 >>> mc.aria2.addUri(['http://example.org/file'])
3276 >>> mc.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent', mode='rb').read()))
3277 >>> r = mc()
3278 >>> tuple(r)
3279 ('2089b05ecca3d829', 'd2703803b52216d1')
3280 system.listMethods()
3282 This method returns all the available RPC methods in an array of
3283 string. Unlike other methods, this method does not require
3284 secret token. This is safe because this method just returns the
3285 available method names.
3286 JSON-RPC Example
3288 >>> import urllib2, json
3290 >>> from pprint import pprint
3291 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3292 ... 'method':'system.listMethods'})
3293 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3294 >>> pprint(json.loads(c.read()))
3295 {u'id': u'qwer',
3296 u'jsonrpc': u'2.0',
3297 u'result': [u'aria2.addUri',
3298 u'aria2.addTorrent',
3299 ...
3300 XML-RPC Example
3302 >>> import xmlrpclib
3304 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3305 >>> s.system.listMethods()
3306 ['aria2.addUri', 'aria2.addTorrent', ...
3307 system.listNotifications()
3309 This method returns all the available RPC notifications in an
3310 array of string. Unlike other methods, this method does not
3311 require secret token. This is safe because this method just
3312 returns the available notifications names.
3313 JSON-RPC Example
3315 >>> import urllib2, json
3317 >>> from pprint import pprint
3318 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3319 ... 'method':'system.listNotifications'})
3320 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3321 >>> pprint(json.loads(c.read()))
3322 {u'id': u'qwer',
3323 u'jsonrpc': u'2.0',
3324 u'result': [u'aria2.onDownloadStart',
3325 u'aria2.onDownloadPause',
3326 ...
3327 XML-RPC Example
3329 >>> import xmlrpclib
3331 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3332 >>> s.system.listNotifications()
3333 ['aria2.onDownloadStart', 'aria2.onDownloadPause', ...
3334 Error Handling
3336 Over JSON-RPC, aria2 returns a JSON object which contains an error code
3337 in code and the error message in message.
3338 Over XML-RPC, aria2 returns faultCode=1 and the error message in fault‐
3340 String.
3341 Options
3343 The same options as for --input-file are available. See the Input File
3344 subsection for a complete list of options.
3345 In the option struct, the name element is the option name (without the
3347 preceding --) and the value element is the argument as a string.
3348 JSON-RPC Example
3350 {'split':'1', 'http-proxy':'http://proxy/'}
3351 XML-RPC Example
3353 <struct>
3354 <member>
3355 <name>split</name>
3356 <value><string>1</string></value>
3357 </member>
3358 <member>
3359 <name>http-proxy</name>
3360 <value><string>http://proxy/</string></value>
3361 </member>
3362 </struct>
3363 The header and index-out options are allowed multiple times on the com‐
3365 mand-line. Since the name should be unique in a struct (many XML-RPC
3366 library implementations use a hash or dict for struct), a single string
3367 is not enough. To overcome this limitation, you may use an array as the
3368 value as well as a string.
3369 JSON-RPC Example
3371 {'header':['Accept-Language: ja', 'Accept-Charset: utf-8']}
3372 XML-RPC Example
3374 <struct>
3375 <member>
3376 <name>header</name>
3377 <value>
3378 <array>
3379 <data>
3380 <value><string>Accept-Language: ja</string></value>
3381 <value><string>Accept-Charset: utf-8</string></value>
3382 </data>
3383 </array>
3384 </value>
3385 </member>
3386 </struct>
3387 The following example adds a download with two options: dir and header.
3389 The header option requires two values, so it uses a list:
3390 >>> import xmlrpclib
3392 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3393 >>> opts = dict(dir='/tmp',
3394 ... header=['Accept-Language: ja',
3395 ... 'Accept-Charset: utf-8'])
3396 >>> s.aria2.addUri(['http://example.org/file'], opts)
3397 '1'
3398 JSON-RPC using HTTP GET
3400 The JSON-RPC interface also supports requests via HTTP GET. The encod‐
3401 ing scheme in GET parameters is based on JSON-RPC over HTTP Specifica‐
3402 tion [2008-1-15(RC1)]. The encoding of GET parameters are follows:
3403 /jsonrpc?method=METHOD_NAME&id=ID¶ms=BASE64_ENCODED_PARAMS
3405 The method and id are always treated as JSON string and their encoding
3407 must be UTF-8.
3408 For example, The encoded string of aria2.tellStatus('2089b05ecca3d829')
3410 with id='foo' looks like this:
3411 /jsonrpc?method=aria2.tellStatus&id=foo¶ms=WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D
3413 The params parameter is Base64-encoded JSON array which usually appears
3415 in params attribute in JSON-RPC request object. In the above example,
3416 the params is ["2089b05ecca3d829"], therefore:
3417 ["2089b05ecca3d829"] --(Base64)--> WyIyMDg5YjA1ZWNjYTNkODI5Il0=
3419 --(Percent Encode)--> WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D
3420 The JSON-RPC interface also supports JSONP. You can specify the call‐
3422 back function in the jsoncallback parameter:
3423 /jsonrpc?method=aria2.tellStatus&id=foo¶ms=WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D&jsoncallback=cb
3425 For Batch requests, the method and id parameters must not be specified.
3427 The whole request must be specified in the params parameter. For exam‐
3428 ple, a Batch request:
3429 [{'jsonrpc':'2.0', 'id':'qwer', 'method':'aria2.getVersion'},
3431 {'jsonrpc':'2.0', 'id':'asdf', 'method':'aria2.tellActive'}]
3432 must be encoded like this:
3434 /jsonrpc?params=W3sianNvbnJwYyI6ICIyLjAiLCAiaWQiOiAicXdlciIsICJtZXRob2QiOiAiYXJpYTIuZ2V0VmVyc2lvbiJ9LCB7Impzb25ycGMiOiAiMi4wIiwgImlkIjogImFzZGYiLCAibWV0aG9kIjogImFyaWEyLnRlbGxBY3RpdmUifV0%3D
3436 JSON-RPC over WebSocket
3438 JSON-RPC over WebSocket uses same method signatures and response format
3439 as JSON-RPC over HTTP. The supported WebSocket version is 13 which is
3440 detailed in RFC 6455.
3441 To send a RPC request to the RPC server, send a serialized JSON string
3443 in a Text frame. The response from the RPC server is delivered also in
3444 a Text frame.
3445 Notifications
3447 The RPC server might send notifications to the client. Notifications is
3448 unidirectional, therefore the client which receives the notification
3449 must not respond to it. The method signature of a notification is much
3450 like a normal method request but lacks the id key. The value of the
3451 params key is the data which this notification carries. The format of
3452 the value varies depending on the notification method. Following noti‐
3453 fication methods are defined.
3454 aria2.onDownloadStart(event)
3456 This notification will be sent when a download is started. The
3457 event is of type struct and it contains following keys. The
3458 value type is string.
3459 gid GID of the download.
3461 aria2.onDownloadPause(event)
3463 This notification will be sent when a download is paused. The
3464 event is the same struct as the event argument of
3465 aria2.onDownloadStart() method.
3466 aria2.onDownloadStop(event)
3468 This notification will be sent when a download is stopped by the
3469 user. The event is the same struct as the event argument of
3470 aria2.onDownloadStart() method.
3471 aria2.onDownloadComplete(event)
3473 This notification will be sent when a download is complete. For
3474 BitTorrent downloads, this notification is sent when the down‐
3475 load is complete and seeding is over. The event is the same
3476 struct of the event argument of aria2.onDownloadStart() method.
3477 aria2.onDownloadError(event)
3479 This notification will be sent when a download is stopped due to
3480 an error. The event is the same struct as the event argument of
3481 aria2.onDownloadStart() method.
3482 aria2.onBtDownloadComplete(event)
3484 This notification will be sent when a torrent download is com‐
3485 plete but seeding is still going on. The event is the same
3486 struct as the event argument of aria2.onDownloadStart() method.
3487 Sample XML-RPC Client Code
3489 The following Ruby script adds http://localhost/aria2.tar.bz2 to aria2c
3490 (running on localhost) with option --dir=/downloads and prints the RPC
3491 response:
3492 #!/usr/bin/env ruby
3494 require 'xmlrpc/client'
3496 require 'pp'
3497 client=XMLRPC::Client.new2("http://localhost:6800/rpc")
3499 options={ "dir" => "/downloads" }
3501 result=client.call("aria2.addUri", [ "http://localhost/aria2.tar.bz2" ], options)
3502 pp result
3504 If you are a Python lover, you can use xmlrpclib (Python3 uses xml‐
3506 rpc.client instead) to interact with aria2:
3507 import xmlrpclib
3509 from pprint import pprint
3510 s = xmlrpclib.ServerProxy("http://localhost:6800/rpc")
3512 r = s.aria2.addUri(["http://localhost/aria2.tar.bz2"], {"dir":"/downloads"})
3513 pprint(r)
3514
3516 Console Readout
3517 While downloading files, aria2 prints a readout to the console to show
3518 the progress of the downloads. The console readout looks like this:
3519 [#2089b0 400.0KiB/33.2MiB(1%) CN:1 DL:115.7KiB ETA:4m51s]
3521 This section describes what these numbers and strings mean.
3523 #NNNNNN
3525 The first 6 characters of the GID as a hex string. The GID is an
3526 unique ID for each download, internal to aria2. The GID is par‐
3527 ticularly useful when interacting with aria2 using the RPC
3528 interface.
3529 X/Y(Z%)
3531 Completed length, the total file length and its progress. If
3532 --select-file is used, this is the sum of selected files.
3533 SEED Share ratio when the aria2 is seeding a finished torrent.
3535 CN The number of connections aria2 has established.
3537 SD The number of seeders aria2 is connected to.
3539 DL Download speed (bytes per second).
3541 UL Upload speed (bytes per second) and the number of uploaded
3543 bytes.
3544 ETA Expected time to finish the download.
3546 When more than one download is in progress, some of the information
3548 described above will be omitted in order to show information for sev‐
3549 eral downloads. And the overall download and upload speeds are shown at
3550 the beginning of the line.
3551 When aria2 is allocating file space or validating checksums, it addi‐
3553 tionally prints the progress of these operations:
3554 FileAlloc
3556 GID, already allocated length and total length in bytes.
3557 Checksum
3559 GID, already validated length and total length in bytes.
3560
3562 HTTP/FTP Segmented Downloads
3563 Download a file
3564 $ aria2c "http://host/file.zip"
3565 NOTE:
3567 To stop a download, press Ctrl-C. You can resume the transfer by
3568 running aria2c with the same argument in the same directory. You can
3569 change URIs as long as they are pointing to the same file.
3570 Download a file from two different HTTP servers
3572 $ aria2c "http://host/file.zip" "http://mirror/file.zip"
3573 Download a file from one host using multiple connections
3575 $ aria2c -x2 -k1M "http://host/file.zip"
3576 NOTE:
3578 The -x option specified the number of allowed connections, while the
3579 -k option specified the size of chunks.
3580 Download a file from HTTP and FTP servers at the same time
3582 $ aria2c "http://host1/file.zip" "ftp://host2/file.zip"
3583 Download files listed in a text file concurrently
3585 $ aria2c -ifiles.txt -j2
3586 NOTE:
3588 -j option specifies the number of parallel downloads.
3589 Using a proxy
3591 For HTTP:
3592 $ aria2c --http-proxy="http://proxy:8080" "http://host/file"
3594 $ aria2c --http-proxy="http://proxy:8080" --no-proxy="localhost,127.0.0.1,192.168.0.0/16" "http://host/file"
3596 For FTP:
3598 $ aria2c --ftp-proxy="http://proxy:8080" "ftp://host/file"
3600 NOTE:
3602 See --http-proxy, --https-proxy, --ftp-proxy, --all-proxy and
3603 --no-proxy for details. You can specify proxy in the environment
3604 variables. See ENVIRONMENT section.
3605 Using a Proxy with authorization
3607 $ aria2c --http-proxy="http://username:password@proxy:8080" "http://host/file"
3608 $ aria2c --http-proxy="http://proxy:8080" --http-proxy-user="username" --http-proxy-passwd="password" "http://host/file"
3610 Metalink Download
3612 Download files with remote Metalink
3613 $ aria2c --follow-metalink=mem "http://host/file.metalink"
3614 Download using a local metalink file
3616 $ aria2c -p --lowest-speed-limit=4000 file.metalink
3617 NOTE:
3619 To stop a download, press Ctrl-C. You can resume the transfer by
3620 running aria2c with the same argument in the same directory.
3621 Download several local metalink files
3623 $ aria2c -j2 file1.metalink file2.metalink
3624 Download only selected files
3626 $ aria2c --select-file=1-4,8 file.metalink
3627 NOTE:
3629 The index is printed to the console using -S option.
3630 Download a file using a local metalink file with user preference
3632 $ aria2c --metalink-location=jp,us --metalink-version=1.1 --metalink-language=en-US file.metalink
3633 BitTorrent Download
3635 Download files using a remote BitTorrent file
3636 $ aria2c --follow-torrent=mem "http://host/file.torrent"
3637 Download using a local torrent file
3639 $ aria2c --max-upload-limit=40K file.torrent
3640 NOTE:
3642 --max-upload-limit specifies the max of upload rate.
3643 NOTE:
3645 To stop a download, press Ctrl-C. You can resume the transfer later
3646 by running aria2c with the same argument in the same directory.
3647 Download using BitTorrent Magnet URI
3649 $ aria2c "magnet:?xt=urn:btih:248D0A1CD08284299DE78D5C1ED359BB46717D8C&dn=aria2"
3650 NOTE:
3652 Don't forget to quote BitTorrent Magnet URIs which include & charac‐
3653 ters with single(') or double(") quotes when specifying URIs on the
3654 command-line.
3655 Download 2 torrents
3657 $ aria2c -j2 file1.torrent file2.torrent
3658 Download a file via torrent and HTTP/FTP server in parallel
3660 $ aria2c -Ttest.torrent "http://host1/file" "ftp://host2/file"
3661 Only download specific files (usually called selected download )
3663 $ aria2c --select-file=1-4,8 file.torrent
3664 NOTE:
3666 The index is printed to the console using -S option.
3667 Download a .torrent file, but do not download the torrent
3669 $ aria2c --follow-torrent=false "http://host/file.torrent"
3670 Specify the output file name
3672 To specify the output file name for BitTorrent downloads, you need to
3673 know the index of file in the torrent (see --show-files). For example,
3674 the output looks like this:
3675 idx|path/length
3677 ===+======================
3678 1|dist/base-2.6.18.iso
3679 |99.9MiB
3680 ---+----------------------
3681 2|dist/driver-2.6.18.iso
3682 |169.0MiB
3683 ---+----------------------
3684 To save 'dist/base-2.6.18.iso' in '/tmp/mydir/base.iso' and
3686 'dist/driver-2.6.18.iso' in '/tmp/dir/driver.iso', use the following
3687 command:
3688 $ aria2c --dir=/tmp --index-out=1=mydir/base.iso --index-out=2=dir/driver.iso file.torrent
3690 Change the listening ports for incoming peer connections
3692 $ aria2c --listen-port=7000-7001,8000 file.torrent
3693 NOTE:
3695 Since aria2 doesn't configure firewalls or routers for port forward‐
3696 ing, it's up to you to do so manually.
3697 Specify conditions to stop seeding after torrent downloads finish
3699 $ aria2c --seed-time=120 --seed-ratio=1.0 file.torrent
3700 NOTE:
3702 In the above example, the program stops seeding after 120 minutes
3703 since download completed or seed ratio reaches 1.0.
3704 Throttle upload speed
3706 $ aria2c --max-upload-limit=100K file.torrent
3707 Enable IPv4 DHT
3709 $ aria2c --enable-dht --dht-listen-port=6881 file.torrent
3710 NOTE:
3712 DHT uses UDP. Since aria2 doesn't configure firewalls or routers for
3713 port forwarding, it's up to you to do it manually.
3714 Enable IPv6 DHT
3716 $ aria2c --enable-dht6 --dht-listen-port=6881 --dht-listen-addr6=YOUR_GLOBAL_UNICAST_IPV6_ADDR
3717 NOTE:
3719 aria2 uses the same ports as IPv4 for IPv6.
3720 Add and remove tracker URIs
3722 Ignore all tracker announce URIs defined in file.torrent and use
3723 http://tracker1/announce and http://tracker2/announce instead:
3724 $ aria2c --bt-exclude-tracker="*" --bt-tracker="http://tracker1/announce,http://tracker2/announce" file.torrent
3726 More advanced HTTP features
3728 Load cookies
3729 $ aria2c --load-cookies=cookies.txt "http://host/file.zip"
3730 NOTE:
3732 You can use Firefox/Mozilla/Chromium's cookie files without modifi‐
3733 cation.
3734 Resume download started by web browsers or other programs
3736 $ aria2c -c -s2 "http://host/partiallydownloadedfile.zip"
3737 NOTE:
3739 This will only work when the initial download was not multi-seg‐
3740 mented.
3741 Client certificate authorization for SSL/TLS
3743 Specify a PKCS12 file as follows:
3744 $ aria2c --certificate=/path/to/mycert.p12
3746 NOTE:
3748 The file specified in --certificate must be contain one PKCS12
3749 encoded certificate and key. The password must be blank.
3750 Alternatively, if PEM files are supported, use a command like the fol‐
3752 lowing:
3753 $ aria2c --certificate=/path/to/mycert.pem --private-key=/path/to/mykey.pem https://host/file
3755 NOTE:
3757 The file specified in --private-key must be decrypted. The behavior
3758 when encrypted one is given is undefined.
3759 Verify SSL/TLS servers using given CA certificates
3761 $ aria2c --ca-certificate=/path/to/ca-certificates.crt --check-certificate https://host/file
3762 NOTE:
3764 This option is only available when aria2 was compiled against GnuTLS
3765 or OpenSSL. WinTLS and AppleTLS will always use the system certifi‐
3766 cate store. Instead of `--ca-certificate install the certificate in
3767 that store.
3768 RPC
3770 Encrypt RPC traffic with SSL/TLS
3771 Specify a server PKC12 file:
3772 $ aria2c --enable-rpc --rpc-certificate=/path/to/server.p12 --rpc-secure
3774 NOTE:
3776 The file specified in --rpc-certificate must be contain one PKCS12
3777 encoded certificate and key. The password must be blank.
3778 Alternatively, when PEM files are supported (GnuTLS and OpenSSL), spec‐
3780 ify the server certificate file and private key file as follows:
3781 $ aria2c --enable-rpc --rpc-certificate=/path/to/server.crt --rpc-private-key=/path/to/server.key --rpc-secure
3783 And more advanced features
3785 Throttle the download speed
3786 Per-download:
3787 $ aria2c --max-download-limit=100K file.metalink
3789 Overall:
3791 $ aria2c --max-overall-download-limit=100K file.metalink
3793 Repair a damaged download
3795 $ aria2c -V file.metalink
3796 NOTE:
3798 Repairing damaged downloads can be done efficiently when used with
3799 BitTorrent or Metalink with chunk checksums.
3800 Drop connections if download speed is lower than a specified limit
3802 $ aria2c --lowest-speed-limit=10K file.metalink
3803 Parameterized URI support
3805 You can specify set of parts:
3806 $ aria2c -P "http://{host1,host2,host3}/file.iso"
3808 You can specify numeric sequence:
3810 $ aria2c -Z -P "http://host/image[000-100].png"
3812 NOTE:
3814 The -Z option is required if the URIs don't point to the same file,
3815 such as in the above example.
3816 You can specify step counter:
3818 $ aria2c -Z -P "http://host/image[A-Z:2].png"
3820 Verifying checksums
3822 $ aria2c --checksum=sha-1=0192ba11326fe2298c8cb4de616f4d4140213837 http://example.org/file
3823 Parallel downloads of an arbitrary number of URIs, metalink, torrent
3825 $ aria2c -j3 -Z "http://host/file1" file2.torrent file3.metalink
3826 BitTorrent Encryption
3828 Encrypt the whole payload using ARC4 (obfuscation):
3829 $ aria2c --bt-min-crypto-level=arc4 --bt-require-crypto=true file.torrent
3831
3833 Project Web Site: https://aria2.github.io/
3834 Metalink Homepage: http://www.metalinker.org/
3836 The Metalink Download Description Format: RFC 5854
3838
3840 Copyright (C) 2006, 2015 Tatsuhiro Tsujikawa
3841 This program is free software; you can redistribute it and/or modify it
3843 under the terms of the GNU General Public License as published by the
3844 Free Software Foundation; either version 2 of the License, or (at your
3845 option) any later version.
3846 This program is distributed in the hope that it will be useful, but
3848 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
3849 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
3850 Public License for more details.
3851 You should have received a copy of the GNU General Public License along
3853 with this program; if not, write to the Free Software Foundation, Inc.,
3854 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
3855 In addition, as a special exception, the copyright holders give permis‐
3857 sion to link the code of portions of this program with the OpenSSL
3858 library under certain conditions as described in each individual source
3859 file, and distribute linked combinations including the two. You must
3860 obey the GNU General Public License in all respects for all of the code
3861 used other than OpenSSL. If you modify file(s) with this exception,
3862 you may extend this exception to your version of the file(s), but you
3863 are not obligated to do so. If you do not wish to do so, delete this
3864 exception statement from your version. If you delete this exception
3865 statement from all source files in the program, then also delete it
3866 here.
38671.34.0 May 15, 2018 ARIA2C(1)