Do aria2 CLI arguments override config file settings?

This article explains the precedence rules between command-line arguments and configuration file settings in the aria2 download utility. When you run aria2, it frequently looks at multiple sources for its configuration, making it crucial to understand which settings take priority. You will learn exactly how aria2 resolves conflicting options and how to leverage this behavior for more flexible download management.

The Rule of Precedence in aria2

The short answer is yes. Command-line arguments always override settings defined in the aria2 configuration file.

When aria2 initializes, it follows a specific order of operations to determine its final runtime settings:

1. Default Values: aria2 loads its internal, hardcoded default values for all options.
2. Configuration File: aria2 reads the configuration file (usually aria2.conf). Any settings defined here will overwrite the default values.
3. Command-Line Arguments: Finally, aria2 parses the arguments you explicitly pass in the terminal command. Any option provided here will overwrite both the defaults and the configuration file settings.

Why This Behavior Matters

This hierarchy allows you to establish a stable, global baseline for your downloads while remaining agile enough to make one-off adjustments.

• Global Defaults: You can use your aria2.conf file to set permanent preferences, such as your maximum download speed, default save directory, or maximum concurrent downloads.
• On-the-Fly Adjustments: If a specific download requires maximum speed or needs to be saved to a different folder, you do not need to edit your configuration file. You simply append the specific flag to your command line, and aria2 will prioritize it for that session only.

A Practical Example

Consider a scenario where your aria2.conf file contains the following line to limit your global download speed:

max-overall-download-limit=1M

If you execute a standard download command, aria2 will cap your speed at 1MB/s:

aria2c https://example.com/file.zip

However, if you are in a hurry and want to bypass this limit for a single, large file, you can override the configuration file by passing the option directly in your terminal:

aria2c --max-overall-download-limit=0 https://example.com/file.zip

In this case, aria2 recognizes the command-line argument (0 for unaltered, unlimited speed) and ignores the 1M limit specified in your configuration file for the duration of that specific download process.