aria2

From the project
home page
:
aria2 is a lightweight multi-protocol & multi-source command-line download utility. It supports
HTTP
/
HTTPS
,
FTP
,
BitTorrent
and
Metalink
. aria2 can be manipulated via built-in
JSON-RPC
and
XML-RPC
interfaces.
Installation
Install
the
aria2
package.
To use aria2 as a
daemon
, you can write a
systemd user unit
.
Configuration
aria2.conf
aria2 looks at
$XDG_CONFIG_HOME/aria2/aria2.conf
for a set of global configuration options by default. This behavior can be modified with the
--conf-path
switch:
The following example downloads
aria2.example.rar
using the options specified in the configuration file
/file/aria2.rapidshare
$ aria2c --conf-path=/file/aria2.rapidshare http://rapidshare.com/files/12345678/aria2.example.rar
If
$XDG_CONFIG_HOME/aria2/aria2.conf
exists and the options specified in
/file/aria2.rapidshare
are desired, the
--no-conf
switch must be appended to the command:
The following example does not use the default configuration file and downloads
aria2.example.rar
using the options specified in the configuration file
/file/aria2.rapidshare
$ aria2c --no-conf --conf-path=/file/aria2.rapidshare http://rapidshare.com/files/12345678/aria2.example.rar
If
$XDG_CONFIG_HOME/aria2/aria2.conf
does not yet exist and you wish to simplify the management of configuration options:
$ touch $XDG_CONFIG_HOME/aria2/aria2.conf
Example aria2.conf
continue
dir=${HOME}/Desktop
file-allocation=none
input-file=${HOME}/.aria2/input.conf
log-level=warn
max-connection-per-server=4
min-split-size=5M
on-download-complete=exit
This is essentially the same as if running the following:
$ aria2c --dir=${HOME}/Desktop --file-allocation=none --input-file=${HOME}/.aria2/input.conf --on-download-complete=exit --log-level=warn FILE
Note
The example aria2.conf above may incorrectly use the $HOME variable. Some users have reported the curly brace syntax to explicitly create a separate ${HOME} subdirectory in the aria2 working directory. Such a directory may be difficult to traverse as bash will consider it to be the $HOME environment variable. For now, it is recommended to use absolute path names in aria2.conf.
Option details
continue
: Continue downloading a partially downloaded file if a corresponding control file exists.
dir=${HOME}/Desktop
: Store the downloaded file(s) in
~/Desktop
.
file-allocation=none
: Do not pre-allocate disk space before downloading begins. (Default: prealloc)
1
input-file=${HOME}/.aria2/input.conf
: Download a list of line, or TAB separated URIs found in
~/.aria2/input.conf
log-level=warn
: Set log level to output warnings and errors only. (Default: debug)
max-connection-per-server=4
: Set a maximum of four (4) connections to each server per file. (Default: 1)
min-split-size=5M
: Only split the file if the size is larger than 2*5MB = 10MB. (Default: 20M)
on-download-complete=exit
: Run the
exit
command and exit the shell once the download session is complete.
Example input file #1
Download
aria2-1.10.0.tar.bz2
from two separate sources to
~/Desktop
before merging as
aria2-1.10.0.tar.bz2
http://aria2.net/files/stable/aria2-1.10.0/aria2-1.10.0.tar.bz2    http://sourceforge.net/projects/aria2/files/stable/aria2-1.10.0/aria2-1.10.0.tar.bz2
Example input file #2
Download
aria2-1.9.5.tar.bz2
and save to
/file/old
as
aria2.old.tar.bz2
http://aria2.net/files/stable/aria2-1.9.5/aria2-1.9.5.tar.bz2
  dir=/file/old
  out=aria2.old.tar.bz2
Download
aria2-1.10.0.tar.bz2
and save to
~/Desktop
as
aria2.new.tar.bz2
http://aria2.net/files/stable/aria2-1.10.0/aria2-1.10.0.tar.bz2
  out=aria2.new.tar.bz2
Additional notes
1
file-allocation=falloc
: Recommended for newer file systems such as
ext4
(with extents support),
btrfs
or
XFS
as it allocates large files (GB) almost instantly. Do not use falloc with legacy file systems such as
ext3
as prealloc consumes approximately the same amount of time as standard allocation would while locking the aria2 process from proceeding to download.
Tip
See
aria2c --help=#all
and
aria2c(1) § OPTIONS
for a complete list of configuration options.
Example aria2.rapidshare
http-user=USER_NAME
http-passwd=PASSWORD
allow-overwrite=true
dir=/file/Downloads
file-allocation=falloc
enable-http-pipelining=true
input-file=/file/input.rapidshare
log-level=error
max-connection-per-server=2
summary-interval=120
Option details
http-user=USER_NAME
: Set HTTP
username
as USER_NAME for password-protected logins. This affects all
URIs
.
http-passwd=PASSWORD
: Set HTTP
password
as PASSWORD for password-protected logins. This affects all URIs.
allow-overwrite=true
: Restart download if a corresponding control file does not exist. (Default: false)
dir=/file/Downloads
: Store the downloaded file(s) in
/file/Downloads
.
file-allocation=falloc
: Call
posix_fallocate(3)
to allocate disk space before downloading begins. (Default: prealloc)
enable-http-pipelining=true
: Enable
HTTP/1.1 pipelining
to overcome network latency and to reduce network load. (Default: false)
input-file=/file/input.rapidshare
: Download a list of single line of TAB separated URIs found in
/file/input.rapidshare
log-level=error
: Set log level to output errors only. (Default: debug)
max-connection-per-server=2
: Set a maximum of two (2) connections to each server per file. (Default: 1)
summary-interval=120
: Output download progress summary every 120 seconds. (Default: 60)
2
Additional notes
Because the
aria2.rapidshare
contains a username and password, it is advisable to set permissions on the file to 600, or similar.
$ cd /file
$ chmod 600 /file/aria2.rapidshare
$ ls -l
total 128M
-rw------- 1 arch users  167 Aug 20 00:00 aria2.rapidshare
2
summary-interval=0
: Suppresses download progress summary output and may improve overall performance. Logs will continue to be output according to the value specified in the
log-level
option.
Tip
The example configuration file can also be applied to
Hotfile
,
DepositFiles
, et.al.
Note
Command-line options always take precedence over options listed in a configuration file.
Example aria2.bittorrent
bt-seed-unverified
max-overall-upload-limit=1M
max-upload-limit=128K
seed-ratio=5.0
seed-time=240
Option details
bt-seed-unverified=false
: Do not check the hash of the file(s) before seeding. (Default: true)
max-overall-upload-limit=1M
: Set maximum overall upload speed to 1MB/sec. (Default: 0)
max-upload-limit=128K
:  Set maximum upload speed per torrent to 128K/sec. (Default: 0)
seed-ratio=5.0
: Seed completed torrents until share ratio reaches 5.0. (Default: 1.0)
seed-time=240
: Seed completed torrents for 240 minutes.
Note
If both
seed-ratio
and
seed-time
are specified, seeding ends when at least one of the conditions is satisfied.
Example aria2.daemon
This configuration can be used to start aria2 as a service. It can be used in conjunction with several of the frontends listed below. Note that rpc-user and rpc-pass are deprecated, but most frontends have not been ported to the new authentication yet. Do not forget to change user, password and Download directory.
continue
daemon=true
dir=/home/aria2/Downloads
file-allocation=falloc
log-level=warn
max-connection-per-server=4
max-concurrent-downloads=3
max-overall-download-limit=0
min-split-size=5M
enable-http-pipelining=true

enable-rpc=true
rpc-listen-all=true
rpc-secret=secret
Frontends
Note
Settings implemented in frontends do not affect
aria2
's own configuration, and it is uncertain whether the different UIs reuse
aria2
configuration if a custom one has been made. Users should ensure their desired parameters are effectively implemented within selected tools and that they are stored persistently (uGet for example has its own
aria2
's command line which sticks across reboots).
Web UIs
Note
These frontends need
aria2c
to be started with
--enable-rpc
in order to work. They are meant to run on your local computer, not on a remote server that downloads using aria
Webui
— Html frontend for aria2.
https://github.com/ziahamza/webui-aria2
||
webui-aria2-git
AUR
aria2rpc
— Command line tool for connecting to a remote instance of
aria2c
. If
aria2c
is installed it can be found under
/usr/share/doc/aria2/xmlrpc/aria2rpc
.
https://github.com/tatsuhiro-t/aria2/blob/master/doc/xmlrpc/aria2rpc
||
aria2
AriaNg
— Pure HTML frontend for aria2. (There is also a desktop client)
https://github.com/mayswind/AriaNg
||
ariang-git
AUR
,
ariang-native-electron-git
AUR
Other UIs
Note
These frontends
do not need
aria2c
to be started with
--enable-rpc
to function.
aria2fe
— A GUI for the CLI-based aria2 download utility.
https://sourceforge.net/projects/aria2fe/
||
aria2fe
AUR
Persepolis
— Graphical front-end for aria2 download manager with lots of features. Supports HTTP and FTP.
https://github.com/persepolisdm/
||
persepolis
uGet
— Feature-rich GTK/CLI download manager which can use aria2 as a back-end by enabling a built-in plugin.
https://ugetdm.com
||
uget
Motrix
— Full-featured download manager that supports downloading HTTP, FTP, BitTorrent, Magnet based on aria2
https://github.com/agalwood/Motrix
||
motrix
AUR
Tips and tricks
Download the packages without installing them
Just use the command below:
# pacman -Sp
packages
| aria2c -i -
pacman -Sp
lists the URLs of the packages on stdout, instead of downloading them, then
|
pipes it to the next command. Finally, the
-i
in
aria2c -i -
switch to
aria2c
means that the URLs for files to be downloaded should be read from the file specified, but if
-
is passed, then read the URLs from stdin.
pacman XferCommand
See
pacman/Tips and tricks#aria2
.
Changing the User Agent
Some sites may filter the requests based on your User Agent, since aria2 is not a well known downloader, it may be good to use a most known downloader or browser as the Aria's User Agent. Just use the
-U
option like this:
$ aria2c -UWget http://some-url-to-download/file.xyz
You can use whatever you want, like
-UMozilla/5.0
and so on.
Using aria2 with makepkg
You can use aria2 instead of
curl
to download source files, just change the
DLAGENTS
variable as follows:
/etc/makepkg.conf
[...]
DLAGENTS=('ftp::/usr/bin/aria2c -UWget -s4 -x4 %u -o %o --follow-metalink=mem'
          'http::/usr/bin/aria2c -UWget -s4 -x4 %u -o %o --follow-metalink=mem'
          'https::/usr/bin/aria2c -UWget -s4 -x4 %u -o %o --follow-metalink=mem'
          'rsync::/usr/bin/rsync --no-motd -z %u %o'
          'scp::/usr/bin/scp -C %u %o')
[...]
Note
Use the
-UWget
option to change the user agent to Wget. It may prevent problems when downloading from sites that filters the requests based on the user agent to provide different responses on what the users uses to access the URL. Since aria2 is a lesser known downloader it may be recognized by the site as a browser instead of a downloader, so changing the user agent to Wget may fix it in most cases. Use the
--follow-metalink=mem
option to avoid downloading the metalink as a separate file and fail the source checksum process.
Using aria2 as a Daemon
To use aria2 as a daemon, you should
write a systemd user unit
. For example:
~/.config/systemd/user/aria2cd.service
[Unit]
Description=aria2 Daemon

[Service]
ExecStart=/usr/bin/aria2c --conf-path=
/path/to/conf
[Install]
WantedBy=default.target
#Example aria2.daemon
shows an example configuration file.
Seed a torrent with aria2
To seed an already downloaded torrent, use the
--check-integrity
option:
$ aria2c --check-integrity=true --seed-ratio=0.0 --dir="/path/to/iso" "/path/to/torrent"
Specifying
--seed-ratio=0.0
will seed the file forever.
Using aria2 with torsocks
Aria2 can be used with
torsocks
for downloading over
Tor
; keep in mind that this is limited to TCP-based protocols, so torrents will not work.
By default, aria2 will try to use its own implementation of a DNS resolver, which does not work under torsocks. This problem can be fixed by passing the
--async-dns=false
option:
$ torsocks aria2c --async-dns=false 'https://fastly.mirror.pkgbuild.com/iso/latest/archlinux-x86_64.iso'
See also
aria2 manual
- Official site
aria2 usage examples
- Official site