pyLoad

Lightweight Python download manager with web interface

pyLoad is a free, open-source download manager written in Python, designed to be extremely lightweight and easily extensible. It supports downloading from one-click hosters, container formats (DLC, CCF, RSDF), and video sites through its plugin system—all fully manageable via a modern web interface.

Installation

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find pyLoad in the catalog (browse Download Clients or search), and click Install. The dashboard sets up the isolated Python virtual environment automatically, streams the install log live, and pyLoad appears in your Application Control panel when it finishes. Reinstall and Remove are in the same Package Management panel. To update, use the amber Update badge on the pyLoad row in the App Dashboard.

What you see and can manage is gated by your account: admins manage any user’s apps; regular users manage their own. For the full package flow see App Management.

Install from the CLI (automation)

The CLI runs the same install and is suited to automation and scripting:

qb install pyload -u username

Directory Layout

Network & Access

pyLoad runs on an auto-assigned port (default 8001) and is accessible through the nginx reverse proxy:

Login:

• Username: Your QuickBox username
• Password: Your QuickBox account password, or the pyLoad password you set for this account

If you change your QuickBox account password later, pyLoad keeps the password it already has. Change it separately if you want them to match.

Change your pyLoad password

The pyLoad password starts as your account password. You can change it at any time without changing your account password. If you set it before installing pyLoad, the install uses that password instead of your account password.

Change it from the Dashboard (recommended)

1. Open the App Dashboard (/dashboard, the default view that lists your installed apps) and find your pyLoad row.
2. Expand the row and open the API & Secrets panel.
3. In the Set field (Change once a password is saved), type the new password and click Save. It must be 6 to 64 characters.
4. To see the password QuickBox has saved, click the eye toggle in the Current field.

The panel shows A pyLoad password is saved when QuickBox holds a pyLoad password for you, or No pyLoad password saved when it does not. The Current field appears only when one is saved. You can only reveal your own pyLoad password. An admin cannot reveal another user’s.

Saving restarts pyLoad if it is running.

Change it from the CLI

qb user pyloadpasswd -u username

The command asks for the new password twice (your input is hidden). See qb user pyloadpasswd for who may set or reveal the password and for the exit codes.

Existing installs

When you update QuickBox with qb update quickbox, any pyLoad login still using the public default password is moved to your account password. A pyLoad password you already changed, in pyLoad’s own settings or through QuickBox, is never overwritten. An update of pyLoad keeps your password. A reinstall resets pyLoad to the password QuickBox saved, so a password you changed only inside pyLoad’s own settings is not kept. To keep a password across a reinstall, set it from the dashboard section above or with qb user pyloadpasswd. If no password was saved, a reinstall uses your account password.

Services

pyLoad uses a templated systemd unit (pyload@.service) running as a forking daemon:

# Check status
systemctl status pyload@username
 
# View logs
journalctl -u pyload@username -f
 
# Restart service
systemctl restart pyload@username

VPN routing

pyLoad can route all of its download traffic through a VPN tunnel using QuickBox Pro’s app-scoped routing, with either a WireGuard or an OpenVPN backend. When routing is enabled, every fetch pyLoad makes to a one-click hoster exits through the VPN peer instead of your server’s real IP.

Why route pyLoad: one-click hosters see and log the IP that requests each download, and they enforce their limits against it: wait timers between files, daily download caps, and outright blocks on datacenter IP ranges. Routing pyLoad through a VPN hides the server’s real IP behind the provider’s exit, and switching to a different VPN server gives you a fresh exit IP that resets those per-IP limits.

pyLoad is a per-user template service (pyload@<user>), so several users can each route their own instance independently, the same as Emby, Jellyfin, and qBittorrent. It appears in the App-Scoped Routing card once pyLoad is installed and its service is running; there is no pre-install staging.

How to enable VPN routing for pyLoad:

1. Go to System > VPN Control (/system/vpn) in the dashboard
2. Upload at least one WireGuard .conf or OpenVPN .ovpn file if you have not done so already
3. Scroll to the App-Scoped Routing card on the VPN Control page
4. Select pyLoad from the app list
5. Choose the tunnel backend and a peer configuration from the dropdown
6. Click Enable Routing

pyLoad restarts inside its VPN network namespace and its downloads exit through the VPN peer from that point forward. The web interface keeps working: pyLoad binds to loopback inside the namespace, and QuickBox routes the dashboard proxy to it automatically, so the https://yourserver.com/username/pyload/ URL and dashboard tile are unaffected.

The default kill-switch stale threshold for pyLoad is 30 minutes, matching qBittorrent and the other downloaders. pyLoad runs long, chunked downloads, so a shorter window risks tearing down routing and aborting an in-progress download during a brief VPN handshake stall. You can adjust it between 60 seconds and 24 hours on the app row inside the App-Scoped Routing card.

For full details on routing configuration, kill switch settings, and live metrics, see the VPN Control dashboard page.

Best Practices

Additional Resources