By default, aria2 checks whether the legacy path $HOME/.aria2/aria2.conf is present, otherwise it parses $XDG_CONFIG_HOME/aria2/aria2.conf as its configuration file. You can specify the path to configuration file using --conf-path option. If you don't want to use the configuration file, use --no-conf option.

The configuration file is a text file and has 1 option per each line. In each line, you can specify name-value pair in the format: NAME=VALUE, where name is the long command-line option name without -- prefix. You can use same syntax for the command-line option. The lines beginning # are treated as comments:

# sample configuration file for aria2c


The confidential information such as user/password might be included in the configuration file. It is recommended to change file mode bits of the configuration file (e.g., chmod 600 aria2.conf), so that other user cannot see the contents of the file.

The environment variables, such as ${HOME}, are expanded by shell. This means that those variables used in configuration file are not expanded. However, it is useful to ${HOME} to refer user's home directory in configuration file to specify file paths. Therefore, aria2 expands ${HOME} found in the following option values to user's home directory:

Note that this expansion occurs even if the above options are used in the command-line. This means that expansion may occur 2 times: first, shell and then aria2c.


Unless the legacy file paths $HOME/.aria2/dht.dat and $HOME/.aria2/dht6.dat are pointing to existing files, the routing table of IPv4 DHT is saved to the path $XDG_CACHE_HOME/aria2/dht.dat and the routing table of IPv6 DHT is saved to the path $XDG_CACHE_HOME/aria2/dht6.dat.


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

If machine name starts ., aria2 performs domain-match instead of exact match. This is an extension of aria2. For example of domain match, imagine the following .netrc entry:

machine login myid password mypasswd
           domain-matches and uses myid and mypasswd.

Some domain-match example follow: does not domain-match does not domain-match because of preceding .. If you want to match, specify


aria2 uses a control file to track the progress of a download. A control file is placed in the same directory as the downloading file and its file name is the file name of downloading file with .aria2 appended. For example, if you are downloading, then the control file should be (There is a exception for this naming convention. If you are downloading a multi torrent, its control file is the "top directory" name of the torrent with .aria2 appended. The "top directory" name is a value of "name" key in "info" directory in a torrent file.)

Usually a control file is deleted once download completed. If aria2 decides that download cannot be resumed(for example, when downloading a file from a HTTP server which doesn't support resume), a control file is not created.

Normally if you lose a control file, you cannot resume download. But if you have a torrent or metalink with chunk checksums for the file, you can resume the download without a control file by giving -V option to aria2c in command-line.


The input file can contain a list of URIs for aria2 to download. 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 --force-sequential and --parameterized-uri options.

Since URIs in the input file are directly read by aria2, they must not be quoted with single(') or double(") quotation.

Lines starting with # are treated as comments and skipped.

Additionally, the following options can be specified after each line of URIs. These optional lines must start with white space(s).

These options have exactly same meaning of the ones in the command-line options, but it just applies to the URIs it belongs to. Please note that for options in input file -- prefix must be stripped.

For example, the content of uri.txt is:

http://server/file.iso http://mirror/file.iso

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.

In some cases, out parameter has no effect. See note of --out option for the restrictions.


This section describes the format of server performance profile. The file is plain text and each line has several NAME=VALUE pair, delimited by comma. Currently following NAMEs are recognized:

Host name of the server. Required.
Protocol for this profile, such as ftp, http. Required.
The average download speed observed in the previous download in bytes per sec. Required.
The average download speed observed in the previous download in bytes per sec. This value is only updated if the download is done in single connection environment and only used by AdaptiveURISelector. Optional.
The average download speed observed in the previous download in bytes per sec. This value is only updated if the download is done in multi connection environment and only used by AdaptiveURISelector. Optional.
How many times the server is used. Currently this value is only used by AdaptiveURISelector. Optional.
Last contact time in GMT with this server, specified in the seconds since the Epoch(00:00:00 on January 1, 1970, UTC). Required.
ERROR is set when server cannot be reached or out-of-service or timeout occurred. Otherwise, OK is set.

Those fields must exist in one line. The order of the fields is not significant. You can put pairs other than the above; they are simply ignored.

An example follows:

host=localhost, protocol=http, dl_speed=32000, last_updated=1222491640, status=OK
                  host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR