pyload-ng

Pre-release

This release is a pre-release and may not be stable for production use.

pyLoad

The free and open-source Download Manager written in pure Python

Overview

pyLoad is a lightweight, pure-Python download manager with a modern web UI and rich plugin ecosystem. It automates downloads from one-click hosters, cloud drives, and many other sources; supports premium accounts, captcha-solving services, and link decryption; and can run headless on servers, NAS devices, or desktops. Designed for extensibility and low resource usage.

Introduction

Cross-platform: works on Linux, macOS, and Windows (Python 3.9+)
Web interface: manage downloads from your browser
Plugin-driven: hundreds of hosters, decrypters, and addons (notifications, schedulers, extractors, etc.)

Quick Start

Open a terminal window and install pyLoad typing:

pip install --pre pyload-ng[all]

To start pyLoad use the command:

pyload

See the usage section for information on all available options.

If you want to uninstall pyLoad:

pip uninstall pyload-ng

Usage

usage: pyload [-h] [-d] [-r] [--storagedir STORAGEDIR] [--userdir USERDIR]
              [--tempdir TEMPDIR] [--dry-run] [--daemon] [--version]

The free and open-source Download Manager written in pure Python

optional arguments:
  -h, --help                    show this help message and exit
  -d, --debug                   enable debug mode
  -r, --reset                   reset default username/password
  --storagedir STORAGEDIR       use this location to save downloads
  --userdir USERDIR             use this location to store user data files
  --tempdir TEMPDIR             use this location to store temporary files
  --dry-run                     test start-up and exit
  --daemon                      run as daemon
  --version                     show program's version number and exit

To start pyLoad, type the command:

pyload

This will create the following directories (if they don't exist already):

~/Downloads/pyLoad: where downloads will be saved.
~/.pyload: where user data and configuration files are stored.
<TMPDIR>/pyLoad: where temporary files are stored. <TMPDIR> is platform-specific.

Note: On Windows, user data and configuration files are stored in the directory ~\AppData\Roaming\pyLoad.

Help

To show an overview of the available options, type:

pyload --help

Web Interface

Open your web browser and visit the url http://localhost:8000 to have access to the pyLoad's web interface.

Default username: pyload.
Default password: pyload.

It's highly recommended to change the default access credentials on first start.

Advanced Installation

Stable Release

Get the latest stable release of pyLoad:

pip install pyload-ng

Note: No stable release yet, pyLoad is now in pre-release phase.

Available modules

pyload.core: pyLoad's heart.
pyload.plugins: the collection of officially supported plugins for pyLoad.
pyload.webui: a web interface to interact with pyLoad.

Development Release

You can force the installation of the latest development release of pyLoad, appending the option --pre to the installation command:

pip install --pre pyload-ng

Do not use development releases in production. Unexpected crashes may occur.

Extra Dependencies

Extra dependencies are non-essential packages that enable additional features of pyLoad.

To install them you have to append a specific tag name to the installation command.

Available tags

plugins: includes packages used by several plugins.
build: includes packages used to build translations.
all: includes both plugins and build packages.

You can use a tag in this way:

pip install pyload-ng[plugins]

Or group more together:

pip install pyload-ng[plugins][build]

Build Translations

Use the command build_locale to retrieve and build the latest locale files (translations):

python setup.py build_locale

Invoke build_locale before building the package (eg. bdist_wheel).

Note:

You don't need to build the translations if you installed pyLoad through pip, they're already included.

Development

Set up your development environment

Clone the repository
Recommended: create a virtual environment for pyLoad

python3 -m venv .venv
source .venv/bin/activate

Install pyLoad as editable install with main and test dependencies

pip install -e ".[test]"

Run pyLoad in debug mode

pyload -d

To run the tests locally

pytest tests

API specification

pyLoad provides an OpenAPI specification for its REST API, visible via Swagger UI under the endpoint

<pyload base url>/api/

The specification file itself is available under

<pyload base url>/api/openapi.json

For reference, there is a local copy of the API specification in openapi-generator/openapi.json. Based on this file, it is possible to generate client code with the official OpenAPI code generator. For example, this command will generate a client for Android, using the dockerized generator:

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i /local/openapi-generator/openapi.json \
  -g java \
  -o /local/openapi-generator/out \
  --additional-properties library=retrofit2,serializationLibrary=gson,openApiNullable=false,hideGenerationTimestamp=true,invokerPackage=org.pyload.android.openapi,apiPackage=org.pyload.android.openapi.api,modelPackage=org.pyload.android.openapi.models

If you are developing a client application for pyLoad, you can use this specification to generate a client in any language / framework the OpenAPI generator supports.

The API specification is parsed from the REST API implementation. The local openapi.json copy should not be edited manually. Instead, if changes have been made to the API, re-generate the specification file by running

pyload --generate-api-spec

which will update the openapi.json file in place.

Report a Vulnerability

Please refer to SECURITY to read our security policy.

Contribute to pyLoad

Please refer to CONTRIBUTING to read our contribution guidelines.

Docker Images

Available images

linuxserver/pyload-ng

Create Container

docker create --name=pyload -v <USERDIR>:/config -v <STORAGEDIR>:/downloads --restart unless-stopped pyload/pyload

Note:

Replace <STORAGEDIR> with the location on the host machine where you want that downloads will be saved.

Replace <USERDIR> with where you want that user data files (configurations) are stored.

Start Container

docker start pyload

Stop Container

docker stop pyload

Show Logs

docker logs -f pyload

Docker Compose

Compatible with docker-compose v2 schemas:

---
version: '2'
services:
  pyload:
    image: pyload
    build: <REPODIR>
    container_name: pyload
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/London
    volumes:
      - <USERDIR>:/config
      - <STORAGEDIR>:/downloads
    ports:
      - 8000:8000 # Webinterface
      - 9666:9666 # Click 'N' Load
    restart: unless-stopped

Note:

Replace <REPODIR> with the location on the host machine where you have checked out the pyload repository.

Replace <STORAGEDIR> with the location on the host machine where you want that downloads will be saved.

Replace <USERDIR> with where you want that user data files (configurations) are stored.

Troubleshooting

pip not found

Retry replacing the command pip with pip3:

pip3 install pyload-ng

If fails again, you may not have the Python interpreter or the pip package manager installed on your system.

Try reinstalling Python to fix this issue.

Visit https://www.python.org/downloads to get the proper Python 3 release for your system.

pyload-ng not found

Check the version of the Python interpreters installed on your system.

To show the version of your default Python interpreter, type the command:

python --version

If the version is too old, try to upgrage Python, then you can retry to install pyLoad.

Python releases below version 3.9 are not supported!

Setuptools is too old

To upgrade the setuptools package, type the command:

pip install --upgrade setuptools

Permission denied

Under Unix-based systems, try to install pyLoad with root privileges.

Prefix the installation/uninstallation command with sudo:

sudo pip install pyload-ng
sudo pip uninstall pyload-ng

Under Windows systems, open a Command Prompt as administrator to install pyLoad with root privileges.

You can also try to install the pyload-ng package without root privileges.

Append the option --user to the installation command:

pip install --user pyload-ng

Licensing

Open Source License

You are allowed to use this software under the terms of the GNU Affero General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Please refer to LICENSE to read the project license.

Alternative License

With an explicit permission of the pyLoad team you may use or distribute this software under a different license according to the agreement.

Contributor License Agreement

Please refer to CLA for the full agreement conditions.

This is essentially what you will be agreeing to:

You claim to have the right to make the contribution (i.e. it's your own work).
You grant the project a perpetual, non-exclusive license to use the contribution.
You grant the project rights to change the outbound license that we use to distribute the code.
You retain full ownership (copyright) of your submission and are free to do with it as you please.

Credits

Please refer to AUTHORS to know a bit more about the people behind pyLoad.

© 2008-2026 pyLoad team

Metadata

Release files for pyload-ng 0.5.0b3.dev100

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyload-ng 0.5.0b3.dev100
File	Size	Uploaded
pyload_ng-0.5.0b3.dev100.tar.gz	1.1 MB	May 17, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pyload-ng 0.5.0b3.dev100
File	Interpreter	ABI	Platform	Reset
pyload_ng-0.5.0b3.dev100-py3-none-any.whl 1.4 MB May 17, 2026	Python 3	none	any	Details

Total release size: 2.5 MB

Release files / pyload_ng-0.5.0b3.dev100.tar.gz

Download URL	pyload_ng-0.5.0b3.dev100.tar.gz
Size	1.1 MB
Tags	Source
SHA-256 checksum How to use checksums	`2f8485f45edd2878a3ceefaba4307fd1bf2bee62846f337a4328fbcf1d2476aa`
BLAKE2b-256 checksum How to use checksums	`9c2a0d3ce47b74cb3489269f9553c78a3140676f6fc057d674529c89b2d55763`
Upload date	May 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Release files / pyload_ng-0.5.0b3.dev100-py3-none-any.whl

Download URL	pyload_ng-0.5.0b3.dev100-py3-none-any.whl
Size	1.4 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`0b154c71d676834cc7591890d456e8ff42d55134d26e9bbb01f236bda2caad47`
BLAKE2b-256 checksum How to use checksums	`b5564ca397aed52716ed1aa69a17d91065b623787295cd9988d3e6b9ce2e8168`
Upload date	May 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`