Skip to content
Get packs

Guide · Open source

How to use webui-aria2: setup, RPC and downloads

Updated · written with AI from the project's own documentation and checked against our catalogue data

WebUI-Aria2 is a browser-based dashboard for aria2, the command-line file downloader. Instead of typing commands, you add, pause and monitor downloads on a graphical page that talks to aria2 over its RPC interface. This guide walks through starting aria2, opening the interface, selecting torrent files and pointing the dashboard at a remote machine.

WebUI-Aria2ziahamza/webui-aria2 · ★ 10.4k · MIT

Quick start

  1. 1Install aria2. Install aria2 using the instructions at aria2.github.io. The dashboard cannot run without it.
  2. 2Start aria2 with RPC. Run aria2c with --enable-rpc and --rpc-listen-all so the dashboard can connect.
  3. 3Open the interface. Open index.html from the docs folder in your browser, or visit the hosted GitHub Pages URL.
  4. 4Add a download. Use the dashboard to add a download, then pause, resume and monitor it from the page.
  5. 5Choose torrent files (optional). Start aria2 with --pause-metadata, then select which files to download from a torrent or metalink.
  6. 6Set DirectURL (optional). If you want to download finished files from the dashboard, configure an HTTP server and enter its URL in configuration.js.

What you need before you start

WebUI-Aria2 does not replace aria2. You must install and start aria2 first, and the dashboard connects to that running process.

The README lists two dependencies: aria2 and a web browser. If aria2 is not installed, the project points to https://aria2.github.io/ for instructions.

  • aria2 installed on your local machine or a remote one
  • A web browser

Start aria2 with RPC enabled

Start aria2 in the background with RPC turned on. The README uses the flags below. The --rpc-listen-all flag lets connections come from other machines, so only use it on a network you trust.

aria2c --enable-rpc --rpc-listen-all

Open the WebUI-Aria2 interface

The README gives three ways to open the interface. Choose the one that fits your setup.

You can download the repository and open index.html from the docs folder in any web browser. You can also visit https://ziahamza.github.io/webui-aria2 directly. Once you have visited that URL, Progressive Web Apps let you open it again while offline.

Alternatively, run the bundled Node.js server from the project folder.

  • Option 1: open index.html from the docs folder
  • Option 2: use the hosted page at ziahamza.github.io/webui-aria2
  • Option 3: run the Node.js server from the project folder
node node-server.js

Select files in torrents or metalinks

You can choose which files to download from a torrent or metalink. Pause a download and a list icon appears next to the settings button. To pick files before the download starts, give aria2 the --pause-metadata flag.

aria2c --enable-rpc --rpc-listen-all --pause-metadata

Connect to aria2 on a remote machine or Raspberry Pi

Because aria2 can run on a home server or a Raspberry Pi, the dashboard is useful as a remote control. The project's Docker images are built for this. The README says the production image for arm32v7 platforms, including Raspberry Pi, bundles aria2 and webui-aria2 together. That image needs aria2.conf to contain at least enable-rpc=true and rpc-listen-all=true. Building it may take several hours because aria2 is compiled from source.

The README also describes a testing Dockerfile for trying the dashboard in a LAN sandbox. It is available at http://localhost:9100 after you run the container.

  • Testing image: port 9100 serves the UI, port 6800 serves aria2 RPC
  • Production ARM image: mount session.txt, aria2.log, aria2.conf and a downloads folder
sudo docker run -v /Downloads:/data -p 6800:6800 -p 9100:8080 --name="webui-aria2" yourname/webui-aria2

Set up DirectURL for downloads from the dashboard

DirectURL lets you download finished files straight from the dashboard. Set up an HTTP server that points at your aria2 download directory and check its permissions. Then enter the full URL, such as http://server:port/, in the DirectURL setting in configuration.js. The README links to directurl.md for a longer explanation.

  • Edit src/js/services/configuration.js to change settings

What people use it for

  • Managing downloads from a browser instead of typing aria2c commands
  • Running aria2 on a home server and controlling it from a laptop or phone browser
  • Running aria2 on a Raspberry Pi with a web dashboard via the ARM Docker image
  • Choosing individual files from a torrent or metalink before downloading

Frequently asked questions

Is webui-aria2 free to use?

The project is released under the MIT License, as stated in the README and LICENSE file. Check the LICENSE file in the repository for the full terms.

Do I need to install aria2 before webui-aria2?

Yes. The README says you must install and start aria2 first, and the interface does not replace it. The dashboard connects to a running aria2 process over RPC.

What does aria2c --enable-rpc --rpc-listen-all do?

It starts aria2 with its RPC interface turned on and listening for connections from other machines. The dashboard uses this interface to add and monitor downloads.

How do I run webui-aria2 on a Raspberry Pi?

The README describes a production Dockerfile for arm32v7 platforms, including Raspberry Pi, which contains both aria2 and webui-aria2. Building it can take several hours. Its aria2.conf must include enable-rpc=true and rpc-listen-all=true.

Why can't I select files in a torrent?

According to the README, you must pause the download to see the file list icon. To choose files before the download starts, give aria2 the --pause-metadata flag.

How does webui-aria2 compare to AriaNg or other aria2 web UIs?

The source names AriaNg, Yet Another Aria2 Web UI and Aria2 WebUI as comparable projects but does not compare their features. Try each one and see which fits your workflow.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

WebUI-Aria2 suits people who already run aria2 and want a visual dashboard, especially on a home server or Raspberry Pi. If you have never used aria2, or you want a standalone desktop downloader without a background process, pick a different tool.

Install options & downloads