How to Limit aria2 Connections per Host?

This article provides a quick guide on how to configure aria2, the lightweight multi-protocol command-line download utility, to restrict the number of concurrent connections it opens to a single server. By default, aggressive downloading can lead to IP bans or server-side throttling. Below, you will find the exact configuration parameters, command-line flags, and implementation examples needed to optimize your download limits and maintain stable connections.

Understanding the Key aria2 Parameters

To control how aria2 interacts with a single host, you need to manipulate two specific configuration options. While one directly limits connections per server, the other determines how a single file can be split.

--max-connection-per-server=<NUM> (Short form: -x) This is the primary setting. It specifies the maximum number of connections to a single server per download. The default value is usually 1, and the maximum allowed value is 16.
--split=<NUM> (Short form: -s) This setting dictates the number of connections/streams used to download a single file. If you set --split higher than --max-connection-per-server, aria2 will still respect the per-server limit unless multiple mirrors (different hosts) are available for the same file.

Method 1: Using Command-Line Flags

If you want to apply the connection limit to a single, one-off download command, pass the -x flag directly in your terminal.

aria2c -x 4 -s 4 "https://example.com/largefile.zip"

In this example, aria2 is strictly capped at opening a maximum of 4 concurrent connections to example.com, ensuring you do not overload the host’s server.

Method 2: Persistent Configuration via aria2.conf

For a permanent solution that applies to all future downloads, add the restrictions to your global aria2 configuration file (typically located at ~/.config/aria2/aria2.conf on Linux/macOS or in the same directory as aria2c.exe on Windows).

Open your configuration file and add or modify the following lines:

# Limit connections to the same server
max-connection-per-server=2

# Set the maximum number of parallel downloads 
max-concurrent-downloads=3

# Set the number of splits per file
split=4

How These Settings Interact

Scenario	Configuration	Resulting Behavior
Single Host	`-x 2 -s 4`	`aria2` will only open 2 connections total because they belong to the same host.
Multiple Mirrors	`-x 2 -s 4` (with 2 different URLs)	`aria2` can open up to 4 connections total (2 to Host A and 2 to Host B).

By carefully balancing the max-connection-per-server variable, you can maximize your download bandwidth without triggering security thresholds on external hosting servers.