Can you pass custom HTTP headers in aria2?

This article provides a straightforward guide on how to pass custom HTTP headers to a server using the aria2 command-line download utility. We will explore the specific command-line option required, look at practical examples for adding single or multiple headers, and explain how to format them correctly to avoid syntax errors.

The --header Option

Yes, it is entirely possible to pass custom HTTP headers using aria2. The utility provides a dedicated command-line option, --header, specifically for this purpose. This is particularly useful when you need to bypass basic anti-scraping measures, mimic specific web browsers, or pass authentication tokens like cookies and bearer tokens to a server.

Basic Syntax and Usage

To append a custom header to your request, you use the --header option followed by the header name and its value enclosed in quotes.

aria2c --header="Header-Name: Value" "URL"

Practical Examples

Here are some common scenarios where you might need to use custom headers with aria2:

  • Setting a Custom User-Agent: If a server blocks the default aria2 user-agent, you can disguise the request as a standard web browser.
aria2c --header="User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)" "https://example.com/file.zip"
  • Passing an Authorization Token: When downloading files from an API or a secured server, you often need to pass an API key or token.
aria2c --header="Authorization: Bearer your_access_token_here" "https://example.com/secure-file.zip"
  • Sending Multiple Headers: If you need to send more than one custom header, you must repeat the --header option for each individual header you want to include.
aria2c --header="X-Custom-Header: MyValue" --header="Accept-Language: en-US" "https://example.com/data.json"

Important Considerations

  • Quotes: Always enclose the header string in double quotes ("...") to ensure that spaces and special characters are parsed correctly by your command-line interface.
  • Colons: Ensure there is a colon and a space (:) separating the header name from its value, adhering to standard HTTP specifications.
  • Configuration File: If you use the same headers frequently, you can add header=Header-Name: Value to your aria2.conf file so you do not have to type it out every time.