Learn Aria2 - Configuration File (aria2.conf)

#Introduction

The last three episodes were full of options: -d, -x, -j, --ftp-user, --continue, and so on. Typing them all every time you run aria2 is tedious and prone to inconsistency — one session forgets -x 4, another forgets -d. This episode changes how you work: all repeated options move into the aria2.conf configuration file, so every download session automatically runs with the same settings.

This pattern resembles other programs you've configured: ~/.bashrc for the shell, ~/.ssh/config for SSH. One file, read automatically at every startup, becoming a consistent policy you don't have to remember.

#Default Location and How to Load It

When it runs, aria2 looks for a configuration file automatically. The primary location is ~/.aria2/aria2.conf — a hidden ~/.aria2 directory in your home. If that file doesn't exist, aria2 checks the XDG config directory (~/.config/aria2/aria2.conf). As long as the file is found, its options apply to all downloads, as if typed on the command line.

Two options govern this behavior:

--conf-path=<PATH> — forces aria2 to read the configuration from a specific path, for example aria2c --conf-path=/etc/aria2/download-server.conf. Useful for selecting different configuration profiles.
--no-conf — disables configuration loading entirely. Handy for debugging when you want to be sure behavior is purely default.

aria2c http://example.com/file.iso

#The aria2.conf Syntax

The syntax is simple and similar to command-line options: one name=value pair per line, without the two-dash (--) prefix. Lines starting with # are treated as comments.

Notice how well this matches the options you already know: max-connection-per-server equals -x, max-concurrent-downloads equals -j, and continue equals -c. Almost every option in the manual has a counterpart in the configuration file, so everything you've learned still applies — only the place you write it changes.

#Using the Home Variable

There's one subtle detail that often confuses people. In the shell, $HOME is expanded before aria2 runs. Inside aria2.conf, that doesn't happen — but aria2 itself expands the home variable for certain options like dir, log, and dht-file-path:

Because the shell doesn't interfere, those two lines truly point to your home directory — not just a literal string. Check the manual for the full list of options that support this kind of expansion.

#Option Precedence

When the same option appears in several places, who wins? The rule is linear and easy to remember:

Command-line options — strongest.
The configuration file — applied if the option isn't given on the command line.
aria2's default values — weakest, used when there's no configuration.

In other words, the configuration provides consistent starting values, but you can still override occasionally. For example, dir in the config points to /srv/downloads, yet if once you run aria2c -d /tmp/x url, that download uses /tmp/x without touching the config. This flexibility is good design: safe defaults, easy overrides.

#A Global Policy for Consistency

The biggest benefit of the configuration file isn't just shorter commands — it's making them a policy. Consider what deserves to stay permanently in the config:

Destination directory (dir) and naming rules — so files don't scatter randomly across the filesystem.
Limits and parallelism (max-concurrent-downloads, max-connection-per-server, split) — so network load is predictable.
Logs and history (log, max-download-result) — an audit trail for every download.
Proxy (all-proxy, http-proxy) — all sessions automatically use the same proxy.
RPC (enable-rpc, rpc-listen-port, rpc-secret) — preparing aria2 as a daemon controllable from a web UI in later episodes.

Because the configuration is just a file, you can also keep several profiles for different roles: one daily-downloader profile, one RPC server profile. Choose via --conf-path, or symlink the active file.

Tip

Since this file can hold credentials like rpc-secret, ftp-passwd, or proxy passwords, file permissions matter. Apply chmod 600 ~/.aria2/aria2.conf so other users can't read its contents — aria2's official documentation recommends the same.

#Configuration Profiles for Different Roles

One configuration file doesn't have to serve every case. You can keep several profiles and pick them via --conf-path. Consider the two most common roles in production: a daily download machine and an RPC server.

dir=${HOME}/downloads
max-concurrent-downloads=3
max-connection-per-server=4
continue=true

The first profile is light and safe for a personal workstation. The second prepares a daemon ready to be controlled remotely — a topic explored more deeply in the later RPC episodes. Picking a profile is just adding --conf-path, for example aria2c --conf-path=$HOME/.aria2/server-rpc.conf url.

Note

Another way to keep multiple profiles tidy: store them all in one directory (say ~/.aria2/conf.d/), then symlink ~/.aria2/aria2.conf to the currently active profile. No command needs to change — aria2 still reads the default location as usual.

#Closing

In episode 8 you moved repeated settings into ~/.aria2/aria2.conf, understood the option=value syntax with comments, loaded specific configurations via --conf-path, disabled it with --no-conf, mastered the precedence order of command line above config above default, and turned the config into a consistent global policy for directories, logs, proxy, RPC, and limits.

The most important takeaway: configuration changes aria2 from commands into policy. Once this file exists, a bare aria2c url is enough — all the technical details run consistently behind the scenes.

In the next episode, episode 9, we enter an exciting new area: BitTorrent — downloading from torrent files and magnet links, seeding behavior, and DHT and peer discovery. See you then!