WeiG qB WebUI: A Beginner’s Guide to qBittorrent’s Alternative WebUI

1. Extract the ZIP

Download the latest stable release weig-qb-webui.zip and extract it. The folder is already named correctly:

weig-qb-webui/
├── public/
├── private/
├── VERSION
└── GIT_SHA

The entire weig-qb-webui folder is the WebUI root. Do not copy only public or private.

2. Move it to a permanent location

Put the whole weig-qb-webui folder somewhere you will not accidentally delete later, for example:

Windows: D:\weig-qb-webui
Linux:   /opt/weig-qb-webui

This is the directory you will enter in qBittorrent.

3. Enable it in qBittorrent

Open qBittorrent:

Tools → Options… → WebUI

These are the current qBittorrent English UI terms. Then:

1. Enable Use alternative WebUI.
2. Find Files location:.
3. Enter the path to the weig-qb-webui folder.

Windows example:

D:\weig-qb-webui

Regular Linux example:

/opt/weig-qb-webui

4. Click OK to save.
5. Refresh the qBittorrent WebUI page. If the old page is still cached, try Ctrl + F5 once.

How do I know the path is correct? The directory you enter should directly contain public, private, VERSION, and the other WebUI files. If you need to enter another weig-qb-webui folder before seeing those files, your path is one level too high or too low.

Docker users: qBittorrent runs inside a container, so you usually cannot enter the host path directly. See the Docker guide below for the difference between host and container paths.

./install.sh

The WebUI itself is installed by default to:

~/.local/share/weig-qb-webui

For example, when running as root, this is usually:

/root/.local/share/weig-qb-webui

First understand “host” and “container”

If qBittorrent is running in Docker on a VPS, Linux server, Synology, QNAP, or another NAS:

• Host: the real Linux/NAS machine that runs Docker — the system you see after SSH login.
• Container: the isolated environment Docker creates for qBittorrent. qBittorrent can directly see container paths, not arbitrary host paths.

For example, your qBittorrent container may have this mapping:

Host:      /root/qbittorrent/config
   ↓ mapped to
Container: /config

A typical Docker Compose entry looks like:

volumes:
  - /root/qbittorrent/config:/config

The left side of the colon, /root/qbittorrent/config, is the host path. The right side, /config, is the container path.

If WeiG qB WebUI is physically installed at:

Host: /root/qbittorrent/config/weig-qb-webui

then qBittorrent Files location: should be:

/config/weig-qb-webui

Do not enter /root/qbittorrent/config/weig-qb-webui in qBittorrent, because the container usually cannot see that host path directly.

Case 1: only one running qBittorrent container

Use the normal one-click command:

curl -fsSL https://weigefenxiang.github.io/WeiG-qB-WebUI/downloads/dev/install.sh -o install.sh && sh install.sh -configure

The installer will try to detect the running qBittorrent container, detect its /config mapping, install the WebUI in the corresponding host location, and configure qBittorrent automatically.

Case 2: find the qBittorrent container name first

If you are not sure what the container is called:

sh install.sh --list-containers

You can also use Docker directly:

docker ps

If the qBittorrent container is named:

qbittorrent

select it explicitly:

sh install.sh --container=qbittorrent -configure

Case 3: multiple qBittorrent containers

For example:

qbittorrent
qbittorrent-test

List them first:

sh install.sh --list-containers

Install for the main qbittorrent container:

sh install.sh --container=qbittorrent -configure

Install for the test container:

sh install.sh --container=qbittorrent-test -configure

The installer will not silently guess between multiple qBittorrent containers.

Case 4: you already know the host directory mounted as /config

For example:

/root/qbittorrent/config

Specify it directly:

sh install.sh --config-root=/root/qbittorrent/config -configure

A Synology path might look like:

sh install.sh --config-root=/volume1/docker/qbittorrent -configure

Another NAS might use something like:

sh install.sh --config-root=/share/Container/qbittorrent -configure

These are examples only. Replace them with the real host path that is mounted as qBittorrent /config.

Case 5: choose the WebUI install path

After selecting a container, you can also choose the container-visible WebUI location:

sh install.sh --container=qbittorrent -o /config/weig-qb-webui -configure

The installer converts the /config/... container path to the corresponding host install path.

Case 6: update multiple existing WebUI directories with one download

For multiple qBittorrent instances, repeat -o. The payload is downloaded and verified once, all targets are prepared before switching, and each target keeps its own latest three backups under ~/.config/weig-qb-webui/backups/.

sh install.sh -dev \
  -o /root/qbittorrent/config/weig-qb-webui \
  -o /root/qbittorrent3/config/weig-qb-webui

Do not add -configure in multi-target mode; each qBittorrent instance keeps its existing Alternative WebUI Root Folder. To see the current command syntax, run sh install.sh -help.

What should I see after installation?

A successful install prints values similar to:

Host install path: /root/qbittorrent/config/weig-qb-webui
qBittorrent Root Folder: /config/weig-qb-webui

Meaning:

• Host install path: where the files are physically stored on the host;
• qBittorrent Root Folder: the container path qBittorrent should use for Files location.

If -configure successfully finds the qBittorrent configuration, the installer enables Use alternative WebUI and sets the path automatically. Otherwise, follow the manual steps in New User Installation → Enable it in qBittorrent above.

C:\Users\<your-username>\AppData\Local\weig-qb-webui

Linux and Windows use the same public option names where practical. Documentation uses lowercase; PowerShell parameter names are case-insensitive.

• Without -dev, the installer uses the verified stable GitHub Release from main. Adding -dev selects the current dev build by exact Git SHA.
• -o means output; repeat it on Linux to update several existing WebUI directories in one verified download.
• Backups live in ~/.config/weig-qb-webui/backups/, with the latest three kept independently for each install target.
• -configure enables Use alternative WebUI and sets Files location in qBittorrent. It can only be used with a single target.
• -rollback restores the selected target’s latest installer-owned backup; repeat -o to roll back multiple explicit targets.
• -uninstall -purge removes the WebUI and that target’s installer-owned backups and rollback state, without touching other targets. Empty shared state folders are cleaned up.
• Leave off -purge if you want to keep backups for a later -rollback.
• -version 1.2.0 selects an exact GitHub Release. A missing release is an error; there is no silent fallback to latest or dev.
• -help lists the currently supported parameters.
• For multiple Docker containers, use --list-containers and --container=NAME, or select the host’s qBittorrent config folder with --config-root=/path.

Specific version and install directory

Linux:

sh install.sh -version 1.2.0 -o /opt/weig-qb-webui -configure

Windows:

powershell -ExecutionPolicy Bypass -File .\install.ps1 -version 1.2.0 -o D:\weig-qb-webui -configure

Rollback

Linux:

sh install.sh -rollback

Windows:

powershell -ExecutionPolicy Bypass -File .\install.ps1 -rollback

The recommended command below performs a complete uninstall without keeping installer backups: it removes the WebUI, disables the matching alternative WebUI configuration, purges installer-owned backups / rollback state for this target, and then deletes the downloaded installer script from the current directory.

Linux / NAS

sh install.sh -uninstall -configure -purge && rm -f -- ./install.sh

For a custom install directory, add -o /path/to/weig-qb-webui.

Docker

Single container / automatic detection:

sh install.sh -uninstall -configure -purge && rm -f -- ./install.sh

Multiple containers:

sh install.sh -uninstall -configure -purge --container=qbittorrent && rm -f -- ./install.sh

When using --config-root:

sh install.sh -uninstall -configure -purge --config-root=/path/to/qbittorrent/config && rm -f -- ./install.sh

Windows PowerShell

powershell -ExecutionPolicy Bypass -File .\install.ps1 -uninstall -configure -purge; if ($LASTEXITCODE -eq 0) { Remove-Item .\install.ps1 -Force }

For a custom install directory, add -o D:\weig-qb-webui.

-purge only removes backups owned by the current uninstall target; it does not touch backups for other installations. When the shared state directory becomes empty, Linux ~/.config/weig-qb-webui (for root: /root/.config/weig-qb-webui) or Windows %APPDATA%\weig-qb-webui is removed as well.

To keep installer backups for a later -rollback, simply omit -purge.