How to Auto Retry Failed Downloads in aria2?

This article provides a quick overview and practical guide on how to configure the command-line download utility aria2 to automatically retry failed downloads. By utilizing specific command-line flags or modifying your configuration file, you can ensure that network hiccups, server timeouts, or temporary errors do not permanently halt your download progress. Below, we explore the essential parameters required to achieve automated retries and how to implement them permanently.

Key Configuration Parameters

To force aria2 to automatically retry a download when an error occurs, you need to adjust a few specific settings. By default, aria2 may give up after a limited number of attempts. You can override this behavior using the following options:

  • --max-tries: This option specifies the maximum number of download attempts. Setting this to 0 means unlimited retries, ensuring aria2 keeps trying until the download succeeds.
  • --retry-wait: This option defines the number of seconds aria2 will wait between successive retry attempts. Setting a reasonable delay (e.g., 5 to 10 seconds) prevents overwhelming the host server.

Implementing the Configuration

There are two primary methods to apply these settings: directly through the command line for one-off downloads, or via a configuration file for a permanent setup.

Method 1: Using Command-Line Flags

If you want to apply the auto-retry behavior to a single download session, append the flags directly to your terminal command.

aria2c --max-tries=0 --retry-wait=10 "your-download-link-here"

In this example, aria2 is instructed to retry the download infinitely (--max-tries=0) and wait 10 seconds between each attempt (--retry-wait=10).

Method 2: Updating the Configuration File

For a permanent solution that applies to all future downloads, add these parameters to your global aria2 configuration file (typically named aria2.conf).

  1. Locate or create your aria2.conf file (usually found in ~/.config/aria2/aria2.conf on Linux/macOS or in the same directory as the executable on Windows).
  2. Open the file in a text editor and add the following lines:
# Absolute maximum number of tries; 0 means unlimited
max-tries=0

# Seconds to wait between retries
retry-wait=10
  1. Save and close the file. The next time you run aria2, it will automatically inherit these settings and retry failed downloads without requiring manual intervention.