Configure aria2 to Prefer IPv4 or IPv6 on Ubuntu Linux

Managing network protocols in aria2 is essential for optimizing download speeds and resolving connectivity issues on Ubuntu. This guide details how to configure aria2 to prioritize IPv4 or IPv6 connections using command-line flags or persistent configuration files. By adjusting these settings, users can prevent timeouts caused by unsupported network types and ensure stable data transfer.

Using Command-Line Arguments

The quickest way to change protocol preferences is by adding flags directly to your aria2 command. This method applies only to the current session.

To force aria2 to use IPv4 only, add the --disable-ipv6 flag:

aria2c --disable-ipv6=true "http://example.com/file.zip"

To force aria2 to use IPv6 only, add the --disable-ipv4 flag:

aria2c --disable-ipv4=true "http://example.com/file.zip"

If you do not specify these flags, aria2 defaults to using both protocols depending on DNS resolution, which can sometimes cause delays if one protocol is unreachable.

Using the Configuration File

For a permanent solution that applies to all downloads, modify the aria2 configuration file. This prevents you from typing flags every time you start a download.

Open or create the configuration file located at ~/.aria2/aria2.conf: bash nano ~/.aria2/aria2.conf
To prefer IPv4, add or uncomment the following line: text disable-ipv6=true
To prefer IPv6, add or uncomment the following line: text disable-ipv4=true
Save the file and exit the editor. If aria2 is running as a daemon, restart the service for changes to take effect: bash sudo systemctl restart aria2

Verifying Your Settings

You can confirm that aria2 is using the correct protocol by checking the verbose output during a download. Run aria2 with the --log-level=debug flag to see connection details.

aria2c --log-level=debug "http://example.com/file.zip"

Look for lines indicating the IP address family. If configured correctly for IPv4, you should only see IPv4 addresses in the connection logs.