Configure Aria2 Max Retries for Specific Errors on Ubuntu

This article guides Ubuntu users through configuring aria2 download retry limits to handle connection failures effectively. It explains the relevant configuration parameters and command-line options available to manage network interruptions. You will learn how to persist these settings to ensure downloads resume automatically after encountering recoverable errors.

Install Aria2 on Ubuntu

Before configuring retries, ensure aria2 is installed on your system. Open your terminal and run the following command to install the package using the apt repository:

sudo apt update
sudo apt install aria2

Edit the Configuration File

Aria2 reads settings from a configuration file located at ~/.aria2/aria2.conf. If this file does not exist, you can create it. Open the file using a text editor like nano:

nano ~/.aria2/aria2.conf

Set Maximum Retry Options

To control how many times aria2 attempts to redownload a file after an error, add or modify the max-tries parameter. While aria2 does not support setting retry counts for individual HTTP status codes separately, this setting applies to all recoverable network and server errors.

Add the following line to your configuration file:

max-tries=10

This setting tells aria2 to attempt the download up to 10 times before giving up. Setting the value to 0 enables unlimited retries.

You should also configure the wait time between retries using the retry-wait option. This prevents overwhelming the server during repeated failures:

retry-wait=5

This sets a 5-second delay between each retry attempt.

Using Command-Line Flags

If you prefer not to edit the configuration file, you can specify retry limits directly in the terminal command when starting a download. This overrides any global settings for that specific session:

aria2c --max-tries=10 --retry-wait=5 https://example.com/file.zip

Verify Configuration

To confirm your settings are active, you can run aria2 with the --show-console-readout flag or check the log output during a download. If the connection fails, aria2 will display the retry count and wait time according to your configuration. These settings ensure robust download management on Ubuntu without requiring manual restarts for transient errors.