Introduction

If you want to run the Aria2 download manager as a persistent background service on your Mac with Apple Silicon (M1, M2, M3), this guide is for you. We will show you how to set up Aria2 with Homebrew services, allowing you to easily start, stop, and manage it as a system-level process. This is the ideal solution for users who need a powerful download manager that runs continuously on their Mac.

Step 1: Install Homebrew and Aria2

First, ensure you have both Homebrew and Aria2 installed on your system. If they are not already installed, follow these steps.

Install Homebrew

Homebrew is the package manager we will use to install and manage Aria2.

1. Visit https://brew.sh/
2. Copy the installation command from the site and run it in Terminal.

1

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. Once the installation is complete, verify it by running:

1

brew --version

Install Aria2

Aria2 is a powerful, multi-source download utility that supports HTTP, HTTPS, FTP, BitTorrent, and Metalink. Install it from Homebrew with this simple command:

1

brew install aria2

Step 2: Create the Aria2 Service File

To run Aria2 as a background service on macOS, you need to create a service configuration file named homebrew.mxcl.aria2.plist. This file allows you to control Aria2 using the brew services command.

1. Open terminal press ⌘ + Space, type Terminal, and hit Enter
2. Navigate to the Aria2 installation directory. The version number will vary, so replace 1.37.0 with your installed version.

1

cd /opt/homebrew/Cellar/aria2/1.37.0/

3. Create the service file use a text editor like nano, vim or nvim to create and edit the homebrew.mxcl.aria2.plist file:
4. Paste the following content into the file. Remember to update two key values:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>KeepAlive</key>
    <true/>
    <key>RunAtLoad</key>
    <true/>
    <key>Label</key>
    <string>homebrew.mxcl.aria2</string>
    <key>ProgramArguments</key>
    <array>
      <string>/opt/homebrew/bin/aria2c</string>
      <string>--enable-rpc=true</string>
      <string>--rpc-secret=REPLACE_WITH_YOUR_SECRET_KEY</string>
      <string>--rpc-allow-origin-all=true</string>
      <string>--rpc-listen-all=true</string>
      <string>--rpc-listen-port=6800</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/$USER/Downloads/</string>
    <key>StandardErrorPath</key>
    <string>/usr/local/var/log/aria2.log</string>
    <key>StandardOutPath</key>
    <string>/usr/local/var/log/aria2.log</string>
  </dict>
</plist>

5. Save and close the file. In nano, you can do this by pressing Ctrl + X, then Y, and then Enter.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

## Disk Settings ##
dir                         = /Volumes/Data/Downloads
daemon                      = false
enable-mmap                 = true
disk-cache                  = 64M
file-allocation             = falloc

## Download Settings ##
continue                    = true
split                       = 16
min-split-size              = 1M
max-tries                   = 3
disable-ipv6                = true
max-connection-per-server   = 16
max-download-limit          = 0
max-upload-limit            = 0
max-overall-upload-limit    = 0
max-overall-download-limit  = 0

## RPC Settings ##
enable-rpc                  = true
rpc-allow-origin-all        = true
rpc-listen-all              = true
rpc-listen-port             = 6800
rpc-secret                  = SECRET

## BT Settings ##
follow-torrent              = true
enable-dht                  = true
enable-dht6                 = true
dht-listen-port             = 6881-6999
max-connection-per-server   = 13
bt-max-peers                = 100
bt-metadata-only            = true
bt-hash-check-seed          = true
bt-enable-lpd               = true
seed-ratio                  = 0.1
enable-peer-exchange        = true
bt-seed-unverified          = true

## Advance Options
allow-overwrite             = false
log-level                   = notice

And make this config like this in homebrew.mxcl.aria2.plist

1
2
3
4
5
6

...
    <array>
      <string>/opt/homebrew/bin/aria2c</string>
      <string>--conf-path=/Users/$USER/.config/aria2/aria2.daemon</string>
    </array>
...

Step 3: Manage the Aria2 Service

With the service file created, you can now start, stop, and check the status of Aria2 using Homebrew services.

• To start the Aria2 as a service, run:

1

brew services start aria2

• To stop theAria2 as a service, run:

1

brew services stop aria2

• To check the status of the Aria2 service:

1

brew services info aria2

Optional: Configure Third-Party Apps

To manage downloads and capture links from your browser, you can use third-party extensions. The following are excellent choices for integrating with your new Aria2 service:

• Aria2 Explorer for Chrome
• Aria2 Integration for Firefox

When configuring these extensions, use the following settings:

• Name: Give a descriptive name for the RPC server.
• Secret: Enter the rpc-secret you defined in your .plist file.
• Host: http://localhost:6800/jsonrpc
• Download Location: /Users/YOUR_USERNAME/Downloads/

Conclusion

By following these steps, you have successfully set up Aria2 to run as a reliable background service on your Apple Silicon Mac using Homebrew. This makes managing your downloads more efficient and ensures Aria2 is always ready to handle new tasks.