# How to Run ReClip with Docker: Complete Setup Guide

> Easily run ReClip with Docker using this complete setup guide. This guide explains how to launch the ReClip Docker container for efficient video downloading and management.

- Repository: [Avery Gan/reclip](https://github.com/averygan/reclip)
- Tags: how-to-guide
- Published: 2026-09-02

---

**ReClip runs as a lightweight Docker container exposing a Flask-based web interface on port 8899, with automatic yt-dlp updates and persistent download storage via Docker volumes.**

ReClip is an open-source media extraction tool packaged as a Docker container for easy deployment. This guide walks you through running ReClip with Docker using either direct `docker run` commands or Docker Compose, based on the official `averygan/reclip` repository structure.

## What the ReClip Docker Image Contains

The ReClip container is built from `python:3.12-slim` and includes three core runtime dependencies:

- **ffmpeg** – handles audio/video processing (installed via `apt-get` in the [Dockerfile](https://github.com/averygan/reclip/blob/main/Dockerfile))
- **yt-dlp** – the media extraction engine that auto-updates on container start via [docker-entrypoint.sh](https://github.com/averygan/reclip/blob/main/docker-entrypoint.sh)
- **Flask** – powers the HTTP API and single-page UI (installed from [requirements.txt](https://github.com/averygan/reclip/blob/main/requirements.txt))

The image configures a non-privileged `reclip` user and prioritizes the user-local yt-dlp binary in `PATH` ([Dockerfile lines 22-24](https://github.com/averygan/reclip/blob/main/Dockerfile)). Port **8899** is exposed for web access.

## Quick Start with Docker Compose (Recommended)

Docker Compose handles building, port mapping, and volume persistence automatically. The [docker-compose.yml](https://github.com/averygan/reclip/blob/main/docker-compose.yml) defines:

- Image build from local Dockerfile
- Port `8899:8899` mapping
- Named volume `reclip-downloads` mounted at `/app/downloads`

Run with a single command:

```bash
docker compose up -d

```

Access the UI at **http://localhost:8899**.

## Running ReClip with Docker Run

For one-off deployments or custom configurations, build and run manually:

```bash
docker build -t reclip .
docker run -d -p 8899:8899 --name reclip \
  -v reclip-downloads:/app/downloads \
  reclip

```

This creates the `reclip-downloads` volume automatically on first run, ensuring downloaded files persist across container restarts.

## Configuration Options

### Disable Automatic yt-dlp Updates

Set `RECLIP_NO_UPDATE=1` to skip the update check on startup:

```bash
docker run -d -p 8899:8899 -e RECLIP_NO_UPDATE=1 reclip

```

By default, [docker-entrypoint.sh](https://github.com/averygan/reclip/blob/main/docker-entrypoint.sh) updates yt-dlp before handing off to Gunicorn.

### Customize the Gunicorn Command

The entrypoint executes any command passed to the container. Override Gunicorn workers or binding:

```bash
docker run -d -p 8899:8899 \
  -v reclip-downloads:/app/downloads \
  reclip gunicorn --workers 4 --bind 0.0.0.0:8899 app:app

```

The default command runs `app:app` from [app.py](https://github.com/averygan/reclip/blob/main/app.py) with standard Gunicorn settings.

## Key Files Reference

| File | Purpose |
|------|---------|
| `Dockerfile` | Container definition: base image, ffmpeg, Python deps, user setup |
| [`docker-entrypoint.sh`](https://github.com/averygan/reclip/blob/main/docker-entrypoint.sh) | Startup script: yt-dlp update, then exec command |
| [`docker-compose.yml`](https://github.com/averygan/reclip/blob/main/docker-compose.yml) | Convenience orchestration with volume persistence |
| [`requirements.txt`](https://github.com/averygan/reclip/blob/main/requirements.txt) | Python dependencies (Flask, yt-dlp) |
| [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) | Flask WSGI application serving UI and API |

## Troubleshooting

**Container exits immediately:** Check logs with `docker logs reclip`. Common causes include port conflicts or missing volume permissions.

**Downloads disappear on restart:** Verify the volume mount with `docker volume ls` and `docker inspect reclip`.

**yt-dlp outdated:** Remove `RECLIP_NO_UPDATE=1` or manually restart the container to trigger an update.

## Summary

- **Docker Compose** (`docker compose up -d`) is the fastest way to run ReClip with proper volume persistence
- **Port 8899** serves the Flask UI; map it explicitly with `-p 8899:8899`
- **Persistent storage** requires mounting `reclip-downloads:/app/downloads`
- **Auto-updates** run on every start unless you set `RECLIP_NO_UPDATE=1`
- The **non-root `reclip` user** and **Gunicorn WSGI server** provide production-ready security

## Frequently Asked Questions

### What base image does ReClip use?

ReClip builds from the official `python:3.12-slim` image. This provides a minimal Python runtime while keeping the image size small. The [Dockerfile](https://github.com/averygan/reclip/blob/main/Dockerfile) layers on ffmpeg via `apt-get` and installs Python dependencies from [requirements.txt](https://github.com/averygan/reclip/blob/main/requirements.txt).

### How do I keep downloaded files after removing the container?

Mount the named volume `reclip-downloads` at `/app/downloads` as shown in the [docker-compose.yml](https://github.com/averygan/reclip/blob/main/docker-compose.yml). Docker manages this volume independently of container lifecycle, so files persist even when you run `docker rm reclip`.

### Can I run ReClip without automatic yt-dlp updates?

Yes. Set the environment variable `RECLIP_NO_UPDATE=1` when starting the container. The [docker-entrypoint.sh](https://github.com/averygan/reclip/blob/main/docker-entrypoint.sh) script checks this variable and skips the `yt-dlp -U` update command when present.

### Why does ReClip use Gunicorn instead of Flask's development server?

Gunicorn provides a production-grade WSGI HTTP server with worker processes, request handling, and proper signal management. The Flask development server in [app.py](https://github.com/averygan/reclip/blob/main/app.py) is only used for direct Python execution; Docker deployments use Gunicorn via the entrypoint script for reliability and performance.