VueTorrent: a Vue 3 replacement WebUI for qBittorrent, installed through the LSIO mod

What VueTorrent actually replaces

qBittorrent ships with its own web interface. VueTorrent is an alternative front end for that interface, built in Vue and Vuetify, and the README is explicit about the boundary: it is a WebUI, described as a visual skin, that uses qBittorrent's WebAPI. Nothing about the BitTorrent client changes. The peer connections, the queue, the tracker announces and the files on disk are all still qBittorrent's.

The audience follows from that. If you run qBittorrent headless on a server, a NAS or a small home box and reach it from a browser, the default interface is functional but dated. VueTorrent targets that setup: people who want transfer graphs, a configurable dashboard and a layout that works on a phone. The README also notes it is optimized for the latest version of qBittorrent and requires 4.4 or newer, which matters if you are pinned to an older build for some other reason.

One consequence of being a front end is worth stating plainly. Because it speaks the same WebAPI, anything that talks to the classic WebUI keeps working. The README calls this out for the *arr stack, and it is the main reason switching is low risk: your automation never sees VueTorrent at all.

How the front end talks to qBittorrent

The repository is a Vite application written in Vue 3 and TypeScript, with Vuetify for components, Pinia for state and axios for HTTP. The build script runs vue-tsc first and then vite build, so type checking is part of producing a release artifact. That artifact is static files, which is why the Dockerfile is three lines: it starts from scratch and copies a single prebuilt binary named /vuetorrent into the image with mode 555. There is no Node runtime in the shipped container.

At runtime the app points at a qBittorrent instance. The sample environment file shows the target variable and two development switches:

VITE_QBITTORRENT_TARGET=http://localhost:8080

VITE_USE_MOCK_PROVIDER=false
VITE_FAKE_TORRENTS_COUNT=5

Setting VITE_USE_MOCK_PROVIDER to true swaps the live API for generated data, and VITE_FAKE_TORRENTS_COUNT controls how many fake entries appear. That is the same mechanism behind the public demo, which the README says runs on mocked data and is not connected to a real qBittorrent instance. It is a sensible design for UI work, and it also means a demo that looks alive tells you nothing about whether your own instance is reachable.

There is a second, optional piece of architecture: vuetorrent-backend. The README describes it as a work in progress that stores server-side settings and says it is not required. Without it, preferences live in the browser, so a new device or a cleared profile means reconfiguring.

Installing VueTorrent: the Docker mod path

The README does not carry install steps. It points at the project wiki's Installation page, so the exact procedure depends on your platform, and the repository's docker-compose.yml shows the pattern the project itself uses for development: a linuxserver/qbittorrent container with an extra environment variable.

services:
  qbit:
    image: linuxserver/qbittorrent:latest
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/London
      - WEBUI_PORT=8080
      - DOCKER_MODS=ghcr.io/vuetorrent/vuetorrent-lsio-mod:latest
    ports:
      - '8080:8080'
      - '6881:6881'
      - '6881:6881/udp'

The line that matters is DOCKER_MODS. The LinuxServer image supports pulling a mod image at startup, and ghcr.io/vuetorrent/vuetorrent-lsio-mod:latest is the one that drops VueTorrent in place of the default web files. Everything else in that file is ordinary qBittorrent configuration: PUID and PGID for file ownership, TZ for the clock, WEBUI_PORT for the listening port, and the 6881 mappings for peer traffic. After the container restarts, browsing to the WebUI port should render the VueTorrent interface rather than the stock one.

If you are not on LinuxServer images, the wiki is the place to look, because this repository does not document a generic install. What it does document is the development route: clone the repo, run npm install, then npm start, and open the WebUI on localhost. The README also flags two things that trip people up there: the default credentials are covered in issue #1720, and host header validation must be disabled in qBittorrent's preferences for the dev server to connect. That last point is a real security setting, so treat it as a local-development concession, not a permanent configuration.

What the dashboard does that the stock WebUI does not

The feature list is where the project earns its place. Torrent operations cover add, remove, pause, resume and rename, plus selective file download and views for info, trackers, peers, content, tags and categories. Search for new torrents is available from inside the WebUI rather than a separate tab. System views show session stats including down and upload speed, session totals and free space, along with transfer graphs.

The parts that are genuinely different from the default interface are smaller and more concrete. The dashboard is configurable: you choose which torrent properties are displayed, separately for busy and completed torrents. Keyboard shortcuts are implemented with a Mac keymap variant, so Cmd substitutes for Ctrl. Ctrl-A selects all torrents, Ctrl-F focuses the search input and pressing it again hands focus to the browser's native search, Delete removes the selection, Ctrl-click toggles multi-select and Shift-click extends a selection range. Escape dismisses dialogs or returns to the dashboard.

Mobile is the other differentiator, and the README states the app can be installed as a PWA. There is also support for qBittorrent Enhanced Edition preferences, which the default interface does not offer. None of this changes what qBittorrent does with your downloads. It changes how much of it you can see and reach from a phone.

Where VueTorrent is the wrong choice

The clearest failure mode is a version mismatch. VueTorrent is built against qBittorrent's WebAPI and the README states a 4.4 or newer requirement, with the project optimized for the latest release. Run it against an older client and the API surface it expects may not exist. That is not a bug you can patch from the front end.

The second limitation is scope. VueTorrent cannot fix anything that is wrong underneath. If qBittorrent is not running, if the WebUI port is not exposed, or if the container cannot write to its download directory, a nicer interface will show you an error rather than a working client. Because it is a skin over the WebAPI, it inherits every limitation of that API: anything the classic WebUI cannot do, VueTorrent cannot do either, unless the optional backend adds it.

There is also a configuration cost. Without vuetorrent-backend, settings are not stored server-side. The README describes the backend as a work in progress that is not required, which is an honest framing but also a warning: if you want your dashboard preferences to follow you between devices, you are depending on a component the project itself labels incomplete. And if you have built tooling or documentation around the exact layout of the stock WebUI, switching means retraining whoever uses it, for a change that is cosmetic in the strict sense.

VueTorrent against qui and Flood

The alternative most often weighed against VueTorrent is qui, another third-party qBittorrent web interface. Both replace the same stock UI and both sit on top of the same WebAPI, so the difference is not capability at the protocol level. It is the stack and the shape of the project. VueTorrent is a Vue 3 and TypeScript application with a Vuetify component layer, and it ships as a static bundle that the LSIO mod drops into a qBittorrent container. If you already run LinuxServer images, that integration is the deciding factor, because it turns the install into one environment variable.

Flood is the other common comparison, and it comes from a different lineage: it was built around its own server component and supports multiple torrent clients rather than being tied to qBittorrent alone. That is a real architectural difference. If you run more than one client, or you want a web UI that is not coupled to qBittorrent's release cadence, Flood's approach is the one to evaluate. If you run qBittorrent and nothing else, VueTorrent's tight coupling is an advantage rather than a constraint, since it can track qBittorrent's API and Enhanced Edition preferences directly.

Maintenance, licence and what to check before upgrading

The repository is not archived, and the last push was on 2026-09-20. Releases are frequent and versioned: v2.35.0 on 2026-08-24, v2.34.1 on 2026-07-14 and v2.34.0 on 2026-05-19, with a CHANGELOG.md and release-please configuration in the tree. A release cadence that dense cuts both ways. You get fixes quickly, and you also get a moving target if you pin a container tag loosely.

Upgrade cost is mostly the qBittorrent version you are running. The README ties compatibility to 4.4 or newer and says the project is optimized for the latest release, so a qBittorrent major bump is the event most likely to break something. The Docker mod tag in the compose file is :latest, which means an unattended container restart can pull a newer VueTorrent than you tested. Pinning a specific tag is the obvious mitigation, though the wiki is the place to confirm which tags are published.

VueTorrent is GPL-3.0. That is a copyleft licence, and it matters most if you redistribute a modified build or bundle it into a product. Running it against your own qBittorrent instance is not redistribution in the ordinary sense, but if your plans go beyond personal use, read the licence text in the repository rather than relying on a summary. This is not legal advice.

Editorial conclusion

Adopt VueTorrent if you already run qBittorrent 4.4 or newer and want a mobile-friendly dashboard, configurable torrent properties and keyboard shortcuts without changing your automation. Skip it if you rely on the classic WebUI's exact layout or need a feature the README does not list, and do not expect it to fix a broken qBittorrent install. Before rolling it out, confirm your qBittorrent version, decide whether the optional vuetorrent-backend is worth running for server-side settings, and check the wiki's installation page for the method that matches your setup.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. VueTorrent/VueTorrent on GitHub