5/10/13

UsageExample aria2 - CLI Metalink/BitTorrent Client

Summary Files Support Report Spam

Log in Create account

Usage Sample
This page describes the usage examples of aria2. For the complete options, see online manual. See also BashCompletion. For XML-RPC interface, see XmlrpcInterface. For IPv6, see also IPv6 Support Status. Make sure that URI is quoted with single(') or double(") quotation if it contains "&" 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 20MiB segment size restriction. So whatever value you specify using -s option, it uses 1 connection per host. Please note that this connection restriction is applied to 1 host. If you specify multiple hosts, aria2 will use them all and open multiple connections. To make it behave like 1.9.x, use -x16 -k1M. See --max- connection-per-server and --min-split-size in the manual page. 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. If you are using newer file systems such as ext4(with extens enabled), btrfs, xfs or NTFS(MinGW32 build only and requires aria2 1.12.0 or later), 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. 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. Index 1. Basic Usage 1. Download a file 2. Download a file using 2 connections 3. Download a file from HTTP and FTP servers 4. Parallel downloads of arbitrary number of URI, metalink, torrent 5. Download files listed in a file concurrently 6. Save error/unfinished downloads on exit 2. Metalink Download 1. Download files with remote metalink 2. Download files with remote Metalink; metalink file itself is processed in 3. Download using a local metalink file 4. Download file using 5 servers 5. Download several local metalink files 6. Print the contents of the metalink file 7. Download only selected files using index 8. Download a file using a local metalink file with user preference 3. BitTorrent Download 1. Download files from remote BitTorrent file 2. Download files from remote BitTorrent file; torrent file itself is 3. Download using a local torrent file 4. Download using BitTorrent Magnet URI 5. Save metadata as .torrent file 6. Adjust the number of peers adaptively 7. Enable DHT 8. Enable IPv6 DHT 9. Add and remove tracker URI 10. Encryption 11. Print the contents of the torrent file: 12. Download only selected files using index (usually called "selectable 13. Change the listening port for incoming peer 14. Specify the condition to stop program after torrent download finished

sourceforge.net/apps/trac/aria2/wiki/UsageExample

1/8

5/10/13

UsageExample aria2 - CLI Metalink/BitTorrent Client

15. Throttle upload speed 16. Seeding already downloaded file 17. Specify file name with index 18. Prioritize piece for previewing files 4. Use With Proxy 1. Set proxy server to use all protocols(HTTP(S)/FTP) 2. Set proxy server to be in HTTP only 3. Use proxy that requires authentication 5. Advanced HTTP Features 1. Load cookies 2. Resume download started by web browsers or another programs 6. Other Advanced Features 1. Throttle download speed 2. Repair a damaged download using -V option 3. Drop connection if download speed is lower than specified value 4. Parameterized URI support 5. Time-stamping 6. Execute command when download finishes 7. Writing to /dev/null 7. Input File

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 or its short form -x option. To download a file using 2 connections from single host: aria2c -x2 http://host/image.iso 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.iso 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.

sourceforge.net/apps/trac/aria2/wiki/UsageExample

2/8

5/10/13

UsageExample aria2 - CLI Metalink/BitTorrent Client

Note: You can specify several options in the input file. See 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 saved 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 memory
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-US file.met

BitTorrent Download
Download files from remote BitTorrent file
aria2c http://site/file.torrent

Download files from remote BitTorrent file; torrent file itself is processed in memory
aria2c --follow-torrent=mem http://site/file.torrent

sourceforge.net/apps/trac/aria2/wiki/UsageExample

3/8

5/10/13

UsageExample aria2 - CLI Metalink/BitTorrent Client

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:248D0A1CD08284299DE78D5C1ED359BB46717D8C&dn The above command will save metadata as a torrent file named as "248d0a1cd08284299de78d5c1ed359bb46717d8c.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 handles HTTP/FTP downloads. On the first torrent download begins, aria2 initiates DHT functionality. After that, 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_UNICAST_IPV6_AD Note: If aria2c is not built with c-ares, --enable-async-dns6 is unnecessary. aria2 shares same port between IPv4 and IPv6 DHT.

Add and remove tracker URI

The following example instructs aria2 to removes all tracker announce URIs described in file.torrent and use "http://tracker1/announce" and "http://tracker2/announce" instead.

aria2c --bt-exclude-tracker="*" --bt-tracker="http://tracker1/announce,http://tracker2/ann

Encryption
By default, aria2 accepts both encrypted/unencrypted connections and it first tries 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 handshake,

sourceforge.net/apps/trac/aria2/wiki/UsageExample

4/8

5/10/13

UsageExample aria2 - CLI Metalink/BitTorrent Client

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 header 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 download")
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 ---+----------------------

sourceforge.net/apps/trac/aria2/wiki/UsageExample

5/8

5/10/13

UsageExample aria2 - CLI Metalink/BitTorrent Client

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-proxy-passwd=' 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%40domain'.

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

sourceforge.net/apps/trac/aria2/wiki/UsageExample

6/8

5/10/13

UsageExample aria2 - CLI Metalink/BitTorrent Client

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".

Writing to /dev/null
aria2c -d /dev -o null --allow-overwrite=true http://example.org/file --allow-overwrite=true is needed to prevent aria2 from renaming existing /dev/null .

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 the manual 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 .

sourceforge.net/apps/trac/aria2/wiki/UsageExample

7/8

5/10/13

UsageExample aria2 - CLI Metalink/BitTorrent Client

2013 SourceForge. All Rights Reserved. SourceForge is a Dice Holdings, Inc. company Terms of Use - Privacy Policy - Cookies/Opt Out

sourceforge.net/apps/trac/aria2/wiki/UsageExample

8/8