https://github.com/manbearwiz/youtube-dl-server
Web / REST interface for downloading youtube videos onto a server.
https://github.com/manbearwiz/youtube-dl-server
docker python rest-api videos youtube-dl
Last synced: 5 months ago
JSON representation
Web / REST interface for downloading youtube videos onto a server.
- Host: GitHub
- URL: https://github.com/manbearwiz/youtube-dl-server
- Owner: manbearwiz
- License: mit
- Created: 2015-02-11T06:51:16.000Z (over 11 years ago)
- Default Branch: main
- Last Pushed: 2026-01-12T08:47:18.000Z (5 months ago)
- Last Synced: 2026-01-15T08:35:29.422Z (5 months ago)
- Topics: docker, python, rest-api, videos, youtube-dl
- Language: Python
- Homepage:
- Size: 234 KB
- Stars: 926
- Watchers: 22
- Forks: 290
- Open Issues: 38
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
[](https://hub.docker.com/r/kmb32123/youtube-dl-server/)
[](https://hub.docker.com/r/kmb32123/youtube-dl-server/)
[](https://raw.githubusercontent.com/manbearwiz/youtube-dl-server/master/LICENSE)
# youtube-dl-server
Very spartan Web and REST interface for downloading youtube videos onto a server. [`starlette`](https://github.com/encode/starlette) + [`yt-dlp`](https://github.com/yt-dlp/yt-dlp).
![screenshot][1]
## Running
### Docker CLI
This example uses the docker run command to create the container to run the app. Here we also use host networking for simplicity. Also note the `-v` argument. This directory will be used to output the resulting videos
```shell
docker run -d --net="host" --name youtube-dl -v /home/core/youtube-dl:/youtube-dl kmb32123/youtube-dl-server
```
To provide custom yt-dlp configuration (e.g., authentication, custom options), mount a config directory:
```shell
docker run -d --net="host" --name youtube-dl \
-v /home/core/youtube-dl:/youtube-dl \
-v /home/core/yt-dlp-config:/root/.config/yt-dlp \
kmb32123/youtube-dl-server
```
Place your `config` file in `/home/core/yt-dlp-config/` with yt-dlp options (one per line). See [yt-dlp configuration documentation](https://github.com/yt-dlp/yt-dlp#configuration) for details.
### Docker Compose
This is an example service definition that could be put in `docker-compose.yml`. This service uses a VPN client container for its networking.
```yml
youtube-dl:
image: "kmb32123/youtube-dl-server"
network_mode: "service:vpn"
volumes:
- /home/core/youtube-dl:/youtube-dl
- /home/core/yt-dlp-config:/root/.config/yt-dlp # optional: custom yt-dlp config
restart: always
```
### Python
If you have python ^3.6.0 installed in your PATH you can simply run like this, providing optional environment variable overrides inline.
```shell
YDL_UPDATE_TIME=False python3 -m uvicorn youtube-dl-server:app --port 8123
```
In this example, `YDL_UPDATE_TIME=False` is the same as the command line option `--no-mtime`.
## 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}}:8080/youtube-dl` and enter the requested `{{url}}`.
#### Curl
```shell
curl -X POST --data-urlencode "url={{url}}" http://{{host}}:8080/youtube-dl/q
```
#### Fetch
```javascript
fetch(`http://${host}:8080/youtube-dl/q`, {
method: "POST",
body: new URLSearchParams({
url: url,
format: "bestvideo"
}),
});
```
#### Bookmarklet
Add the following bookmarklet to your bookmark bar so you can conviently send the current page url to your youtube-dl-server instance.
```javascript
javascript:!function(){fetch("http://${host}:8080/youtube-dl/q",{body:new URLSearchParams({url:window.location.href,format:"bestvideo"}),method:"POST"})}();
```
## Implementation
The server uses [`starlette`](https://github.com/encode/starlette) for the web framework and [`youtube-dl`](https://github.com/rg3/youtube-dl) to handle the downloading. The integration with youtube-dl makes use of their [python api](https://github.com/rg3/youtube-dl#embedding-youtube-dl).
This docker image is based on [`python:alpine`](https://registry.hub.docker.com/_/python/) and consequently [`alpine:3.8`](https://hub.docker.com/_/alpine/).
[1]:youtube-dl-server.png