Metadata-Version: 2.2
Name: gallery-dl-server
Version: 0.7.0
Summary: Web UI for downloading media with gallery-dl and yt-dlp.
Author-email: qx6ghqkz <qx6ghqkz@proton.me>
Maintainer-email: qx6ghqkz <qx6ghqkz@proton.me>
License: The MIT License (MIT)
        
        Copyright (c) 2015 Kevin Brey
        Copyright (c) 2024-2025 qx6ghqkz
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Documentation, https://github.com/qx6ghqkz/gallery-dl-server#readme
Project-URL: Repository, https://github.com/qx6ghqkz/gallery-dl-server
Project-URL: Issues, https://github.com/qx6ghqkz/gallery-dl-server/issues
Project-URL: Releases, https://github.com/qx6ghqkz/gallery-dl-server/releases
Project-URL: Docker, https://hub.docker.com/r/qx6ghqkz/gallery-dl-server
Keywords: image,gallery,video,media,downloader,server,web-ui,self-hosted,gallery-dl,youtube,yt-dlp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: gallery_dl<2.0.0,>=1.28.1
Requires-Dist: jinja2<4.0.0,>=3.1.5
Requires-Dist: python-multipart>=0.0.20
Requires-Dist: requests<3.0.0,>=2.32.3
Requires-Dist: starlette<1.0.0,>=0.45.1
Requires-Dist: uvicorn<1.0.0,>=0.32.0; (platform_machine != "x86_64" and platform_machine != "AMD64") or implementation_name != "cpython"
Requires-Dist: uvicorn[standard]<1.0.0,>=0.32.0; (platform_machine == "x86_64" or platform_machine == "AMD64") and implementation_name == "cpython"
Requires-Dist: websockets>=13.1
Requires-Dist: yt-dlp>=2024.11.04
Provides-Extra: full
Requires-Dist: brotli>=1.1.0; implementation_name == "cpython" and extra == "full"
Requires-Dist: brotlicffi>=1.1.0; implementation_name != "cpython" and extra == "full"
Requires-Dist: mutagen>=1.47.0; extra == "full"
Requires-Dist: pycryptodomex>=3.21.0; extra == "full"
Requires-Dist: pyyaml>=6.0.2; extra == "full"
Requires-Dist: toml>=0.10.2; python_version <= "3.10" and extra == "full"
Provides-Extra: build
Requires-Dist: build>=1.2.2; extra == "build"
Requires-Dist: pip>=24.3; extra == "build"
Requires-Dist: pyinstaller>=6.10.0; extra == "build"
Requires-Dist: setuptools>=75.6.0; extra == "build"
Requires-Dist: wheel>=0.45.0; extra == "build"
Provides-Extra: dev
Requires-Dist: pre-commit>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.9.0; extra == "dev"

[![Docker Stars Shield](https://img.shields.io/docker/stars/qx6ghqkz/gallery-dl-server.svg?style=flat-square)](https://hub.docker.com/r/qx6ghqkz/gallery-dl-server/)
[![Docker Pulls Shield](https://img.shields.io/docker/pulls/qx6ghqkz/gallery-dl-server.svg?style=flat-square)](https://hub.docker.com/r/qx6ghqkz/gallery-dl-server/)
[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://raw.githubusercontent.com/qx6ghqkz/gallery-dl-server/master/LICENSE)

# gallery-dl-server

Web UI for [`gallery-dl`](https://github.com/mikf/gallery-dl) with support for downloading videos via [`yt-dlp`](https://github.com/yt-dlp/yt-dlp).

![screenshot](https://raw.githubusercontent.com/qx6ghqkz/gallery-dl-server/refs/heads/main/images/gallery-dl-server.png)

## Running

### Docker CLI

This example uses the `docker run` command to create the container to run the app.

```shell
docker run -d \
  --name gallery-dl \
  -p 9080:9080 \
  -e UID=1000 \
  -e GID=1000 \
  -v "/path/to/config:/config" \
  -v "/path/to/downloads:/gallery-dl" \
  --restart on-failure \
  qx6ghqkz/gallery-dl-server:latest
```

### Docker Compose

This is an example service definition that could be put in `docker-compose.yaml`. This service uses a VPN client container for its networking.

[Gluetun](https://github.com/qdm12/gluetun) is recommended for VPN usage. See [docs/docker-compose.yaml](https://github.com/qx6ghqkz/gallery-dl-server/blob/main/docs/docker-compose.yaml) for a template.

```yaml
services:
  gallery-dl:
    image: qx6ghqkz/gallery-dl-server:latest
    container_name: gallery-dl
    network_mode: container:vpn
    # ports:
    #   - 9080:9080
    environment:
      - UID=1000
      - GID=1000
    volumes:
      - "/path/to/config:/config"
      - "/path/to/downloads:/gallery-dl"
    restart: on-failure
```

#### Important Notes

- Make sure you mount the directory containing the config file rather than the file itself. This ensures changes to the config file are propagated to the running Docker container and you will not need to restart the container. More information on this issue [here](https://github.com/moby/moby/issues/15793#issuecomment-135411504).

- The output download directory depends on the `base-directory` in your gallery-dl config file. Make sure it is the absolute path `/gallery-dl/` instead of the relative path `./gallery-dl/` or you will need to mount your download directory to `/usr/src/app/gallery-dl` instead (not recommended).

- You can use the environment variables `UID` and `GID` to change the user ID and group ID of the user running the server process. This is important because downloaded files will be owned by that user. Make sure the IDs match those of the user on your host system. The default `UID:GID` is `1000:1000` when left unspecified.

### Python

If you have Python 3.10 or later (3.12 is recommended) installed and on your PATH, you can simply run the server using the command line. Clone this repository and install the dependencies located in `requirements.txt` in a virtual environment.

Run the command below in the root folder while inside the virtual environment. On Windows, replace `python3` with `python`.

```shell
python3 -m gallery_dl_server --host "0.0.0.0" --port "9080"
```

The command-line arguments are optional. By default, the server will run on host `0.0.0.0` and an available port will be selected if one is not provided.

To view the full list of command-line arguments, perform `python3 -m gallery_dl_server -h`. These arguments can also be specified as environment variables.

### Installation

The package can be installed with Python along with its dependencies by performing `pip install .` in the root directory of the repository. To install optional dependencies, perform `pip install .[full]`. It is recommended to install in a virtual environment to avoid dependency conflicts.

Installation will allow running directly from the command line via the command `gallery-dl-server`. The log file will be created directly in the home directory of the user as long as the package is not in the current working directory.

### Standalone Executable

On Windows, the program can be run using the prebuilt executable (.exe) file, which includes a Python interpreter and the required Python packages. Prebuilt executables for each release can be found in [Releases](https://github.com/qx6ghqkz/gallery-dl-server/releases).

By default, any available port will be selected. To select a specific port, run the executable from the command line and specify the port, and optionally host, as a command-line argument.

```cmd
gallery-dl-server.exe --host "0.0.0.0" --port "9080"
```

When run as an executable, the log file will be created in a `logs` folder in the same directory as the executable. Configuration files can also be loaded from the same directory as the executable. The bundled releases contain a default configuration file in JSON, YAML and TOML formats.

### Dependencies

All required and optional Python and non-Python dependencies are included in the Docker image and will be available in the running container, however if you are running gallery-dl-server using any of the other methods, i.e. not with a Docker container, there are some considerations.

In order to run with Python, the dependencies in `requirements.txt` need to be installed in the running Python environment. These Python dependencies are included in the standalone executable and do not need to be installed.

Installation with `pip install .` only installs the required dependencies. To install all dependencies, including optional dependencies, use `pip install .[full]`.

#### Optional Dependencies

- [brotli](https://github.com/google/brotli) or [brotlicffi](https://github.com/python-hyper/brotlicffi): Brotli content encoding support
- [mutagen](https://github.com/quodlibet/mutagen): embed metadata and thumbnails in certain formats
- [pycryptodomex](https://github.com/Legrandin/pycryptodome): decrypt AES-128 HLS streams and other forms of data
- [pyyaml](https://pyyaml.org): YAML configuration file support
- [toml](https://pypi.org/project/toml): TOML configuration file support (<= Python 3.10 only)

Non-Python dependencies are **not included** in any form. The most important of these and strongly recommended is [FFmpeg](https://ffmpeg.org), which is required primarily by yt-dlp for video and audio conversion and should be accessible from the command line, i.e. on the PATH. There is also [MKVToolNix](https://mkvtoolnix.download/index.html), which includes [mkvmerge](https://www.matroska.org/downloads/mkvtoolnix.html) for accurate [Ugoira](https://www.pixiv.help/hc/en-us/articles/235584628-What-are-Ugoira) frame timecodes.

Dependencies for [gallery-dl](https://github.com/mikf/gallery-dl#dependencies) and [yt-dlp](https://github.com/yt-dlp/yt-dlp#dependencies) are documented in their respective repositories. The majority of these are optional Python dependencies and can safely be ignored, however the [strongly recommended dependencies](https://github.com/yt-dlp/yt-dlp#strongly-recommended) should be installed.

### Port Mapping

By default, this service listens on port 9080. You can use any value for the host port, but if you would like to map to a different internal container port, you need to set the `CONTAINER_PORT` environment variable. This can be done using the `-e` flag with `docker run` or in a Docker Compose file.

For example, if you need to run multiple instances of gallery-dl-server using [Gluetun](https://github.com/qdm12/gluetun) for the networking (every instance must use a different internal port), you can specify an internal port other than the default 9080.

All services defined in the same `docker-compose.yaml` file:

```yaml
services:
  gallery-dl:
    image: qx6ghqkz/gallery-dl-server:latest
    container_name: gallery-dl
    depends_on:
      - gluetun
    network_mode: service:gluetun
    ...

  gallery-dl-2:
    image: qx6ghqkz/gallery-dl-server:latest
    container_name: gallery-dl-2
    environment:
      - CONTAINER_PORT=9090
    depends_on:
      - gluetun
    network_mode: service:gluetun
    ...

  gluetun:
    image: qmcgaw/gluetun:latest
    container_name: gluetun
    ports:
      # gallery-dl
      - 9080:9080
      # gallery-dl-2
      - 9090:9090
    ...
```

## Configuration

Configuration of gallery-dl is as documented in the [official documentation](https://github.com/mikf/gallery-dl#configuration). A configuration file is **required.**

If run outside of Docker, the [default locations](https://github.com/mikf/gallery-dl#locations) will be used to search for a configuration file. If run as an executable, the current directory will also be searched for a valid configuration file.

Additionally, YAML and TOML configuration files are supported at any of the pre-defined locations.

When run with Docker, the configuration file must be mounted inside the `/config` directory inside the container.

### Locations

- `/config/gallery-dl.conf`
- `/config/gallery-dl.{yaml, yml}`
- `/config/gallery-dl.toml`
- `/config/config.json`
- `/config/config.{yaml, yml}`
- `/config/config.toml`

A [default configuration file](https://github.com/qx6ghqkz/gallery-dl-server/blob/main/docs/gallery-dl.conf) for use with gallery-dl-server has been provided and will automatically be placed in the directory mounted to `/config` if no valid configuration file exists in that location.

For more information on configuration file options, see [gallery-dl/docs/configuration.rst](https://github.com/mikf/gallery-dl/blob/master/docs/configuration.rst).

Any additional locations specified in the configuration file must also exist inside the Docker container. For example, if you specify a cookies file location, ensure that location is accessible from within the Docker container.

It is recommended you place any additional files such as archive, cache and cookies files inside the same directory mounted to `/config` along with the configuration file.

## Usage

### Start a download remotely

Downloads can be triggered by supplying the `{{url}}` of the requested video through the Web UI or through the REST interface via curl, etc.

#### HTML

Just navigate to `http://{{host}}:9080/gallery-dl` and enter the requested `{{url}}`.

#### Curl

```shell
curl -X POST --data-urlencode "url={{url}}" http://{{host}}:9080/gallery-dl/q
```

#### Fetch

```javascript
fetch(`http://${host}:9080/gallery-dl/q`, {
  method: "POST",
  body: new URLSearchParams({
    url: url
  }),
});
```

#### Bookmarklet

Add the following bookmarklet to your bookmark bar so you can conveniently send the current page URL to your gallery-dl-server instance.

```javascript
javascript:!function(){fetch("http://${host}:9080/gallery-dl/q",{body:new URLSearchParams({url:window.location.href}),method:"POST"})}();
```

## Implementation

The server uses [`starlette`](https://github.com/encode/starlette) for the web framework with [`gallery-dl`](https://github.com/mikf/gallery-dl) and [`yt-dlp`](https://github.com/yt-dlp/yt-dlp) to handle the downloading. The integration with gallery-dl uses Python as described [here](https://github.com/mikf/gallery-dl/issues/642). For video downloads, gallery-dl imports yt-dlp.

The Docker image is based on [`python:alpine`](https://registry.hub.docker.com/_/python/) and consequently [`alpine`](https://hub.docker.com/_/alpine/).

## Useful Links

### gallery-dl

- Documentation: [gallery-dl/README.rst](https://github.com/mikf/gallery-dl/blob/master/README.rst)
- Config file outline: [gallery-dl/wiki/config-file-outline](https://github.com/mikf/gallery-dl/wiki/config-file-outline)
- Configuration options: [gallery-dl/docs/configuration.rst](https://github.com/mikf/gallery-dl/blob/master/docs/configuration.rst)
- List of supported sites: [gallery-dl/docs/supportedsites.md](https://github.com/mikf/gallery-dl/blob/master/docs/supportedsites.md)

### yt-dlp

- Documentation: [yt-dlp/README.md](https://github.com/yt-dlp/yt-dlp/blob/master/README.md)
- List of supported sites: [yt-dlp/supportedsites.md](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md)
- List of extractors: [yt-dlp/yt_dlp/extractor/_extractors.py](https://github.com/yt-dlp/yt-dlp/blob/master/yt_dlp/extractor/_extractors.py)

### Issues

- [gallery-dl/issues/642](https://github.com/mikf/gallery-dl/issues/642)
- [gallery-dl/issues/1680](https://github.com/mikf/gallery-dl/issues/1680)
