= Usage Sample =

This page describes the usage examples of aria2. For the complete options,
see [http://aria2.sourceforge.net/aria2c.1.html aria2c(1) man page].
See also BashCompletion.
For XML-RPC interface, see XmlrpcInterface. For IPv6, see also [wiki:Ipv6Support
IPv6 Support Status].
'''Make sure that URI is quoted with single(') or double(") quotation if it cont
ains "&" or any characters that have special meaning in shell.'''
'''As of 1.10.0 release, aria2 uses 1 connection per host by default and has 20M
iB segment size restriction.'''
So whatever value you specify using '''-s''' option, it uses 1 connection per ho
st.
Please note that this connection restriction is applied to 1 host. If you specif
y multiple hosts, aria2 will use them all and open multiple connections.
To make it behave like 1.9.x, use '''--max-connection-per-server'''={{{4}}} '''-
-min-split-size'''={{{1M}}}
By default, aria2 allocates files before download them to
prevent possible fragmentation. But it is reported that it uses
50%-90% CPU and slows down their PCs on some platforms.[[BR]]
If you are using newer file systems such as ext4(with extens
enabled), btrfs or xfs, I recommend to
use '''--file-allocation'''={{{falloc}}}. It allocates
large(few GiB) files almost instantly and it doesn't slow down
your PC at all.[[BR]]
For linux users,
specifying '''--enable-direct-io'''={{{true}}} (enabled by
default since 1.0.0) greatly reduces CPU usage to 1%.[[BR]]
If you are neither using cutting edge file systems nor Linux user and mind this
slow down, turn off file allocation by
giving '''--file-allocation'''={{{none}}}.
If you forget about the full name of options or its details, put '''-h''' before
the option or words in
option name,
like '''aria2c -hcrypt'''. aria2 searches options which contains specified words
and print their usage.
You can leave other options or URIs when using '''-h''' option.
If aria2 finds '''-h''', it stops after printing the help message.
[[PageOutline(2-4,Index,inline)]]
== Basic Usage ==
=== Download a file ===
{{{
aria2c http://host/image.iso
}}}
''Note:
As of 1.10.0, aria2 uses 1 connection per host in each download.
You can change this using '''--max-connection-per-server''' option.
''
''Note:
To stop a download, press
{{{Ctrl-C}}}.
You can resume the transfer by running aria2c with the same arguments
at the same directory.
You can change URIs as long as they are pointing to the same file.
''
=== Download a file using 2 connections ===
{{{
aria2c -s2 http://host/image.iso http://mirror1/image.iso http://mirror2/image.i
so
}}}
''Note:
If you specify URIs more than the value of '''-s''' option, for this example, 2,
first 2 URIs are used and 3rd URI is used for backup, which means if one
of first 2 URIs are failed then 3rd is kicked in.
''
=== Download a file from HTTP and FTP servers ===
{{{
aria2c http://host1/file.zip ftp://host2/file.zip
}}}
=== Parallel downloads of arbitrary number of URI, metalink, torrent ===
{{{
aria2c -Z http://host/file1 file2.torrent file3.metalink
}}}
''Note:
If you specify only torrent or metalink file stored in your local disk,
then '''-Z''' option is not required. So you can do:
''
{{{
aria2c file1.torrent file2.torrent
}}}
=== Download files listed in a file concurrently ===
{{{
aria2c -ifiles.txt -j5
}}}
''Note:
'''-j''' option specifies the number of concurrent downloads.
You can include local torrent and metalink files in a list file.
''
''Note:
You can specify several options in the input file. See
[wiki:UsageExample#InputFile Input File] section.
''
=== Save error/unfinished downloads on exit ===
{{{
aria2c -ifiles.txt --save-session=out.txt
}}}
When you press {{{Ctrl-C}}} or aria2 exits, all error/unfinished downloads are s
aved in ''out.txt''.
Note that downloads added by '''aria2.addTorrent''' and '''aria2.addMetalink'''
XML-RPC method are not saved.
You can use this file as an input file to restart downloads:
{{{
aria2c -iout.txt
}}}
== Metalink Download ==
=== Download files with remote metalink ===
{{{
aria2c http://host/file.metalink
}}}
=== Download files with remote Metalink; metalink file itself is processed in me
mory ===
{{{
aria2c --follow-metalink=mem http://host/file.metalink
}}}
=== Download using a local metalink file ===
{{{
aria2c -t10 --lowest-speed-limit=4000 file.metalink
}}}
''Note:
To stop a download, press {{{Ctrl-C}}}.
You can resume the transfer by running aria2c with the same arguments
at the same directory.
''
=== Download file using 5 servers ===
{{{
aria2c -C5 file.metalink
}}}
''Note:
With metalink file, '''-s''' option has no effect.
Use '''-C''' option instead.
''
=== Download several local metalink files ===
{{{
aria2c file1.metalink file2.metalink
}}}
=== Print the contents of the metalink file ===
{{{
aria2c -S file.metalink
}}}
=== Download only selected files using index ===
{{{
aria2c --select-file=1-4,8 -Mfile.metalink
}}}
''Note:
The index is printed to the console using '''-S''' option.
''
=== Download a file using a local metalink file with user preference ===
{{{
aria2c --metalink-location=JP,US --metalink-version=1.1 --metalink-language=en-U
S file.metalink
}}}
== !BitTorrent Download ==
=== Download files from remote !BitTorrent file ===
{{{
aria2c http://site/file.torrent
}}}
=== Download files from remote !BitTorrent file; torrent file itself is processe
d in memory ===
{{{
aria2c --follow-torrent=mem http://site/file.torrent
}}}
=== Download using a local torrent file ===
{{{
aria2c -u40K /path/to/file.torrent
}}}
''Note:
'''-u''', '''--max-upload-limit''' specifies the max upload rate.''
''Note:
To stop a download, press {{{Ctrl-C}}}.
You can resume the transfer by running aria2c with the same arguments
at the same directory.
''
You can download multiple torrents.
{{{
aria2c /path/to/file1.torrent /path/to/file2.torrent
}}}
=== Download using !BitTorrent Magnet URI ===
{{{
aria2c "magnet:?xt=urn:btih:248D0A1CD08284299DE78D5C1ED359BB46717D8C&dn=aria2"
}}}
''NOTE:
Don't forget to quote !BitTorrent Magnet URI which includes "&"
character with single(') or double(") quotation.
It is strongly recommended to enable DHT when you use Magnet URI.
See '''--enable-dht''' option.
''
=== Save metadata as .torrent file ===
{{{
aria2c --bt-save-metadata "magnet:?xt=urn:btih:248D0A1CD08284299DE78D5C1ED359BB4
6717D8C&dn=aria2"
}}}
The above command will save metadata as a torrent file named as "248d0a1cd082842
99de78d5c1ed359bb46717d8c.torrent"
=== Adjust the number of peers adaptively ===
If the whole download speed of every torrent is lower than 200K,
aria2 temporarily increases the number of peers to try for more
download speed.
{{{
aria2c --bt-request-peer-speed-limit=200K file.torrent
}}}
''Note:
Configuring '''--bt-request-peer-speed-limit''' option with your preferred
download speed can increase your download speed in some cases.
''
=== Enable DHT ===
{{{
aria2c --enable-dht http://site/file.torrent
}}}
''Note:
Since 1.7.2, DHT is enabled by default. DHT doesn't start while aria2 only handl
es HTTP/FTP downloads.
On the first torrent download begins, aria2 initiates DHT functionality. After t
hat, DHT runs until aria2 exits.
Prior 1.7.2, DHT is disabled by default.
''
=== Enable IPv6 DHT ===
{{{
aria2c --enable-dht6 --dht-listen-port=6881 --dht-listen-addr6=YOUR_GLOBAL_UNICA
ST_IPV6_ADDR --enable-async-dns6
}}}
''Note:
If aria2c is not built with c-ares, '''--enable-async-dns6''' is unnecessary. ar
ia2 shares same port between IPv4 and IPv6 DHT.
=== Add and remove tracker URI ===
The following example instructs aria2 to removes all tracker announce URIs descr
ibed in file.torrent and use "!http://tracker1/announce" and "!http://tracker2/a
nnounce" instead.
{{{
aria2c --bt-exclude-tracker="*" --bt-tracker="http://tracker1/announce,http://tr
acker2/announce" file.torrent
}}}
=== Encryption ===
By default, aria2 accepts both encrypted/unencrypted connections and it first tr
ies encryption(obfuscation) handshake and if it fails then falls back to legacy
!BitTorrent handshake.
To instruct aria2 to only accept and establish connection with encryption handsh
ake,
{{{
aria2c --bt-require-crypto=true http://site/file.torrent
}}}
There are 2 types of encryption: header only or full connection.
By default, if both types of encryption are provided by peer, aria2 chooses head
er only encryption. To instruct aria2 to always use full connection encryption,
{{{
aria2c --bt-min-crypto-level=arc4 http://site/file.torrent
}}}
=== Print the contents of the torrent file: ===
{{{
aria2c -S file.torrent
}}}
=== Download only selected files using index (usually called "selectable downloa
d") ===
{{{
aria2c --select-file=1-4,8 -Tfile.torrent
}}}
''Note:
The index is printed to the console using '''-S''' option.
''
=== Change the listening port for incoming peer ===
{{{
aria2c --listen-port=6881-6883 file.torrent
}}}
''Note:
Make sure that the specified ports are open for incoming/outgoing TCP
traffic.
''
=== Specify the condition to stop program after torrent download finished ===
{{{
aria2c --seed-time=120 --seed-ratio=1.0 file.torrent
}}}
''Note:
In the above example, the program exists when the 120 minutes has elapsed
since download completed or seed ratio reaches 1.0.
''
=== Throttle upload speed ===
{{{
aria2c --max-upload-limit=100K file.torrent
}}}
=== Seeding already downloaded file ===
You can seed downloaded file using '''-V''' option.
This will first check piece hashes for the downloaded file.
{{{
aria2c -V -d/path/to/dir file.torrent
}}}
If you are sure the file is correct, then use '''--bt-seed-unverified''' option
to skip hash check before seeding.
{{{
aria2c --bt-seed-unverified -d/path/to/dir file.torrent
}}}
You can seed multiple torrents.
{{{
aria2c --bt-seed-unverified -d/path/to/dir file1.torrent file2.torrent
}}}
=== Specify file name with index ===
To specify output filename for !BitTorrent downloads, you need to know the index
of file in torrent file using '''-S'''
option. For example, the output of '''-S''' option looks like this:
{{{
idx|path/length
===+======================
1|dist/base-2.6.18.iso
|99.9MiB
---+----------------------
2|dist/driver-2.6.18.iso
|169.0MiB
---+----------------------
}}}
To save ''dist/base-2.6.18.iso'' in ''/tmp/mydir/base.iso'' and ''dist/driver-2.
6.18.iso'' in ''/tmp/dir/driver.iso'',
use the following command:
{{{
aria2c --dir=/tmp --index-out=1=mydir/base.iso --index-out=2=dir/driver.iso file
.torrent
}}}
''Note: The '''--index-out''' option with http URI to torrent file
doesn't work. It only works with local torrent files.
aria2 doesn't remember the file path specified in '''--index-out'''
option. You have to specify '''--index-out''' option every time for
resuming or seeding. aria2 doesn't warn you if you forget this
option, so be careful.
''
=== Prioritize piece for previewing files ===
Download first 1MiB of each file in a torrent with high priority.
{{{
aria2c --bt-prioritize-piece=head file.torrent
}}}
== Use With Proxy ==
=== Set proxy server to use all protocols(HTTP(S)/FTP) ===
{{{
aria2c --all-proxy='http://proxy:8080' http://host/file
}}}
''Note:
'''--all-proxy''' option can be overrode by protocol specific
proxy options: '''--http-proxy''', '''--https-proxy''' and
'''--ftp-proxy'''.
''
=== Set proxy server to be in HTTP only ===
{{{
aria2c --http-proxy='http://proxy:8080' http://host/file
}}}
=== Use proxy that requires authentication ===
{{{
aria2c --http-proxy='http://proxy:8080' --http-proxy-user='username' --http-prox
y-passwd='password' http://host/file
}}}
{{{
aria2c --http-proxy='http://username:password@proxy:8080' http://host/file
}}}
''Note:
{{{username}}} and {{{password}}} should be percent-encoded.
For example, if username is 'myid@domain', then percent-encoded form is 'myid%40
domain'.
''
== Advanced HTTP Features ==
=== Load cookies ===
Load Mozilla/Firefox(1.x/2.x) and Netscape format:
{{{
aria2c --load-cookies=cookies.txt http://host/file
}}}
Load Firefox3 format:
{{{
aria2c --load-cookies=cookies.sqlite http://host/file
}}}
''Note:
You can use Firefox/Mozilla's cookie file without modification.
''
=== Resume download started by web browsers or another programs ===
{{{
aria2c -c -s2 http://host/partiallydownloadedfile.zip
}}}
== Other Advanced Features ==
=== Throttle download speed ===
{{{
aria2c --max-download-limit=100K http://host/file
}}}
=== Repair a damaged download using -V option ===
{{{
aria2c -V file.metalink
}}}
''Note:
This option is only available used with BitTorrent or metalink with chunk
checksums.
''
=== Drop connection if download speed is lower than specified value ===
{{{
aria2c --lowest-speed-limit=10K file.metalink
}}}
=== Parameterized URI support ===
You can specify set of parts:
{{{
aria2c -P http://{host1,host2,host3}/file.iso
}}}
You can specify numeric sequence using []:
{{{
aria2c -Z -P http://host/image[000-100].png
}}}
''Note:
'''-Z''' option is required if the all URIs don't point to the same
file, such as the above example.
''
You can specify step counter:
{{{
aria2c -Z -P http://host/image[A-Z:2].png
}}}
=== Time-stamping ===
aria2 gets timestamp of a file from the remote server and apply it to the local
file.
{{{
aria2c -R http://host/file.iso
}}}
=== Execute command when download finishes ===
{{{
aria2c --on-download-complete=COMMAND http://example.org/file.iso
}}}
See also '''--on-download-error''', '''--on-download-start''' and
'''--on-download-stop''' option, or run "{{{aria2c -h#hook}}}".
== Input File ==
The input file can contain list of URIs to feed them into aria2. You
can specify multiple URIs for a single entity: separate URIs on a
single line using the TAB character.
Each line is treated as if it is provided in command-line argument.
Therefore they are affected by '''-Z''' and '''-P'''
options.
Additionally, options can be specified after each
line of URIs.
See Input File section in [http://aria2.sourceforge.net/aria2c.1.html aria2c] ma
n page for complete list of available options.
These options have exactly same meaning of the ones in the
command-line options, but it just applies to the URIs it belongs
to.
For example, let the content of uri.txt be:
{{{
http://server/file.iso http://mirror/file.iso
dir=/iso_images
out=file.img
http://foo/bar
}}}
If aria2 is executed with '''-i''' {{{uri.txt}}} '''-d''' {{{/tmp}}} options,
then ''file.iso'' is saved as ''/iso_images/file.img'' and it is downloaded from
!http://server/file.iso and !http://mirror/file.iso.
The file ''bar'' is downloaded from !http://foo/bar and saved as ''/tmp/bar''.