How to Set Max Retry Attempts in aria2?

This article provides a quick overview of how to configure the maximum number of retry attempts for failed downloads in the aria2 command-line utility. You will learn the exact parameter to use, its default behavior, and how to apply it via both the command line and configuration files to ensure more resilient file transfers.

The Max Tries Parameter: --max-tries

In aria2, the parameter used to set the maximum number of retry attempts for a download is --max-tries.

When aria2 encounters a transient error—such as a dropped connection, a server timeout, or a temporary network glitch—it will automatically attempt to reconnect and resume the download. By configuring this parameter, you control exactly how many times aria2 will try to salvage the download before officially marking it as failed.

Default Behavior and Syntax

• Default Value: 5
• Infinite Retries: Setting the value to 0 forces aria2 to retry indefinitely until the download completes or is manually stopped.

To use this parameter in your terminal, append it to your download command followed by the desired number of attempts:

aria2c --max-tries=10 "https://example.com/file.zip"

If you want to ensure a critical download never gives up due to a flaky network connection, you can set it to infinite:

aria2c --max-tries=0 "https://example.com/large-dataset.iso"

Complementary Settings

To make your retry strategy even more effective, --max-tries is often paired with the following parameters:

• --retry-wait: Defines the number of seconds to wait between retry attempts. The default setting is 0 seconds (immediate retry), but increasing this can help when dealing with rate-limited servers.
• --timeout: Sets the timeout duration in seconds before a connection attempt is considered failed, which subsequently triggers a retry.

Permanent Configuration

If you prefer not to type the parameter every time, you can add it directly to your aria2 configuration file (usually named aria2.conf):

# Always retry up to 15 times before giving up
max-tries=15
# Wait 5 seconds between each retry attempt
retry-wait=5