aria2 - The ultra fast download utility

Author: Tatsuhiro Tsujikawa


This program comes with no warranty. You must use this program at your own risk.


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

The project page is located at

See aria2 Online Manual (Russian translation) and the usage examples to learn how to use aria2.


Here is a list of features:

How to get source code

We maintain the source code at Github:

To get the latest source code, run following command:

$ git clone git://

This will create aria2 directory in your current directory and source files are stored there.


features dependency
BitTorrent libnettle+libgmp or libgcrypt or OpenSSL
Metalink libxml2 or Expat.
Checksum libnettle or libgcrypt or OpenSSL
gzip, deflate in HTTP zlib
Async DNS C-Ares
Firefox3/Chromium cookie libsqlite3
XML-RPC libxml2 or Expat.
JSON-RPC over WebSocket libnettle or libgcrypt or OpenSSL


libxml2 has precedence over Expat if both libraries are installed. If you prefer Expat, run configure with --without-libxml2.


GnuTLS has precedence over OpenSSL if both libraries are installed. If you prefer OpenSSL, run configure with --without-gnutls --with-openssl.


libnettle has precedence over libgcrypt if both libraries are installed. If you prefer libgcrypt, run configure with --without-libnettle --with-libgcrypt. If OpenSSL is selected over GnuTLS, neither libnettle nor libgcrypt will be used.

A user can have one of the following configurations for SSL and crypto libraries:

You can disable BitTorrent and Metalink support by providing --disable-bittorrent and --disable-metalink to the configure script respectively.

In order to enable async DNS support, you need c-ares.

How to build

In order to build aria2 from the source package, you need following development packages(package name may vary depending on the distribution you use):

You can use libgcrypt-dev instead of nettle-dev and libgmp-dev:

You can use libssl-dev instead of libgnutls-dev, nettle-dev, libgmp-dev, libgpg-error-dev and libgcrypt-dev:

You can use libexpat1-dev instead of libxml2-dev:

You may also need pkg-config to detect the above mentioned libraries.

On Fedora you need the following packages: gcc, gcc-c++, kernel-devel, libgcrypt-devel, libgcrypt-devel, libxml2-devel, openssl-devel

If you downloaded source code from git repository, you have to run following command to generate configure script and other files necessary to build the program:

$ autoreconf -i

Also you need Sphinx to build man page.

If you are building aria2 for Mac OS X, take a look at, which builds OSX universal binary DMG.

The quickest way to build aria2 is first run configure script:

$ ./configure

To build statically linked aria2, use ARIA2_STATIC=yes command-line option:

$ ./configure ARIA2_STATIC=yes

After configuration is done, run make to compile the program:

$ make

See Cross-compiling Windows binary to create Windows binary. See Cross-compiling Android binary to create Android binary.

The configure script checks available libraries and enables the features as much as possible because all the features are enabled by default.

Since 1.1.0, aria2 checks the certificate of HTTPS servers by default. If you build with OpenSSL or the recent version of GnuTLS which has gnutls_certificate_set_x509_system_trust() function and the library is properly configured to locate the system-wide CA certificates store, aria2 will automatically load those certificates at the startup. If it is not the case, I recommend to supply the path to the CA bundle file. For example, in Debian the path to CA bundle file is '/etc/ssl/certs/ca-certificates.crt' (in ca-certificates package). This may vary depending on your distribution. You can give it to configure script using --with-ca-bundle option:

$ ./configure --with-ca-bundle='/etc/ssl/certs/ca-certificates.crt'
$ make

Without --with-ca-bundle option, you will encounter the error when accessing HTTPS servers because the certificate cannot be verified without CA bundle. In such case, you can specify the CA bundle file using aria2's --ca-certificate option. If you don't have CA bundle file installed, then the last resort is disable the certificate validation using --check-certificate=false.

By default, bash_completion file named aria2c is installed to the directory $prefix/share/doc/aria2/bash_completion. To change the install directory of the file, use --with-bashcompletiondir option.

The executable is 'aria2c' in src directory.

aria2 uses CppUnit for automated unit testing. To run the unit test:

$ make check

Cross-compiling Windows binary

In this section, we describe how to build Windows binary using mingw-w64 cross-compiler on Debian Linux.

Basically, after compiling and installing depended libraries, you can do cross-compile just passing appropriate --host option and specifying CPPFLAGS, LDFLAGS and PKG_CONFIG_LIBDIR variables to configure. For convenience and lowering our own development cost, we provide easier way to configure the build settings.

mingw-config script is a configure script wrapper for mingw-w64. We use it to create official Windows build. This script assumes following libraries have been built for cross-compile:

Some environment variables can be adjusted to change build settings:

cross-compile to build programs to run on HOST. It defaults to i686-w64-mingw32. To build 64bit binary, specify x86_64-w64-mingw32.
Prefix to the directory where dependent libraries are installed. It defaults to /usr/local/$HOST. -I$PREFIX/include will be added to CPPFLAGS. -L$PREFIX/lib will be added to LDFLAGS. $PREFIX/lib/pkgconfig will be set to PKG_CONFIG_LIBDIR.

For example, to build 64bit binary do this:

$ HOST=x86_64-w64-mingw32 ./mingw-config

Cross-compiling Android binary

In this section, we describe how to build Android binary using Android NDK cross-compiler on Debian Linux.

android-config script is a configure script wrapper for Android build. We use it to create official Android build. This script assumes the following libraries have been built for cross-compile:

When building the above libraries, make sure that disable shared library and enable only static library. We are going to link those libraries statically.

We use zlib which comes with Android NDK, so we don't have to build it by ourselves.

android-config assumes following points:

Before running android-config and android-make, $ANDOIRD_HOME environment variable must be set to point to the correct path.

After android-config, run android-make to compile sources.

Building documentation

Sphinx is used to build the documentation. aria2 man pages will be build when you run make if they are not up-to-date. You can also build HTML version of aria2 man page by make html. The HTML version manual is also available at online (Russian translation).


About filename

The filename of the downloaded file is determined as follows:

single-file mode
If "name" key is present in .torrent file, filename is the value of "name" key. Otherwise, filename is the basename of .torrent file appended by ".file". For example, .torrent file is "test.torrrent", then filename is "test.torrent.file". The directory to store the downloaded file can be specified by -d option.
multi-file mode
The complete directory/file structure mentioned in .torrent file is created. The directory to store the top directory of downloaded files can be specified by -d option.

Before download starts, a complete directory structure is created if needed. By default, aria2 opens at most 100 files mentioned in .torrent file, and directly writes to and reads from these files. The number of files to open simultaneously can be controlled by --bt-max-open-files option.


aria2 supports mainline compatible DHT. By default, the routing table for IPv4 DHT is saved to $HOME/.aria2/dht.dat and the routing table for IPv6 DHT is saved to $HOME/.aria2/dht6.dat. aria2 uses same port number to listen on for both IPv4 and IPv6 DHT.

Other things should be noted

  • -o option is used to change the filename of .torrent file itself, not a filename of a file in .torrent file. For this purpose, use --index-out option instead.
  • The port numbers that aria2 uses by default are 6881-6999 for TCP and UDP.
  • aria2 doesn't configure port-forwarding automatically. Please configure your router or firewall manually.
  • The maximum number of peers is 55. This limit may be exceeded when download rate is low. This download rate can be adjusted using --bt-request-peer-speed-limit option.
  • As of release 0.10.0, aria2 stops sending request message after selective download completes.


netrc support is enabled by default for HTTP(S)/FTP. To disable netrc support, specify -n command-line option. Your .netrc file should have correct permissions(600).


The WebSocket server embedded in aria2 implements the specification defined in RFC 6455. The supported protocol version is 13.