# How to Install ReClip Self-Hosted Media Downloader: 3 Methods (Native, Docker, Compose)

> Install ReClip self-hosted media downloader with native, Docker, or Docker Compose methods. Easily download media from 1000+ sites with bundled yt-dlp and ffmpeg.

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

---

**Run ReClip locally using the native installation script, Docker, or Docker Compose — all three methods bundle yt-dlp and ffmpeg for downloading media from 1000+ sites.**

ReClip is a lightweight, self-hosted media downloader built with Python and Flask. The entire backend lives in a single file ([`app.py`](https://github.com/averygan/reclip/blob/main/app.py)), making deployment straightforward whether you prefer native processes or containerized environments. This guide covers every installation method with exact commands pulled from the `averygan/reclip` source code.

## Prerequisites

Before installing ReClip, verify you have the required tools:

| Tool | Version | Purpose |
|------|---------|---------|
| **Python** | 3.8+ | Runs the Flask backend in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) |
| **yt-dlp** | latest | Core downloader supporting 1000+ sites |
| **ffmpeg** | recent | Audio extraction for MP3 downloads |
| **Git** | any | Cloning the repository |
| **Docker** | 20.10+ | Required only for containerized installs |

The native installation script automatically checks these prerequisites. If tools are missing, it suggests Homebrew (macOS) or APT (Debian/Ubuntu) commands — see lines 5-29 of [`reclip.sh`](https://github.com/averygan/reclip/blob/main/reclip.sh) for the detection logic.

## Method 1: Native Installation (Recommended)

The fastest way to run ReClip for local development uses the provided Bash wrapper.

### Step 1: Install System Dependencies

```bash

# macOS

brew install yt-dlp ffmpeg

# Debian/Ubuntu

sudo apt install yt-dlp ffmpeg -y

```

### Step 2: Clone and Run

```bash
git clone https://github.com/averygan/reclip.git
cd reclip
./reclip.sh

```

### What the Script Does

The [`reclip.sh`](https://github.com/averygan/reclip/blob/main/reclip.sh) helper performs four operations automatically:

1. **Creates a virtual environment** (lines 33-41) if `venv/` doesn't exist
2. **Installs Python dependencies**: `pip install -q flask yt-dlp`
3. **Updates yt-dlp** to the latest release (lines 44-48)
4. **Launches the server** on port 8899 (line 56)

When complete, you'll see:

```

ReClip is running at http://localhost:8899

```

## Method 2: Docker Installation

For isolated environments, the `Dockerfile` bundles all dependencies into a single image.

```bash

# Build from repository root

docker build -t reclip .

# Run with port 8899 exposed

docker run -p 8899:8899 reclip

```

The Dockerfile copies [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) and [`templates/index.html`](https://github.com/averygan/reclip/blob/main/templates/index.html), installs Python dependencies, and declares `EXPOSE 8899`. The container starts the Flask app automatically.

## Method 3: Docker Compose Installation

For persistent deployments with automatic restart, use the provided [`docker-compose.yml`](https://github.com/averygan/reclip/blob/main/docker-compose.yml):

```bash
docker compose up --build

```

This maps port 8899 host-to-container and configures restart policies for production use.

## Verifying Your Installation

Test the running instance using the API endpoints defined in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py):

```bash

# Fetch video metadata

curl -X POST http://localhost:8899/api/info \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

# Start an MP3 download

curl -X POST http://localhost:8899/api/download \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","format":"audio"}'

```

## How ReClip Processes Downloads

The backend in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) (~150 lines) handles downloads through these routes:

| Endpoint | Function | Implementation |
|----------|----------|----------------|
| `/api/info` | Video metadata | Runs `yt-dlp -j <url>`, extracts title, thumbnail, formats (lines 97-106) |
| `/api/download` | Start download | Spawns background thread with `run_download()`, stores files in `downloads/` |
| `/api/status/<job_id>` | Track progress | Returns job state and filename |
| `/api/file/<job_id>` | Retrieve file | Serves completed download |
| `/api/playlist` | Playlist parsing | Uses `yt-dlp --flat-playlist -J` (lines 43-60) |

## Key Source Files

Reference these files when customizing your ReClip self-hosted media downloader installation:

- **[`reclip.sh`](https://github.com/averygan/reclip/blob/main/reclip.sh)** — Native setup automation with prerequisite checking
- **[`app.py`](https://github.com/averygan/reclip/blob/main/app.py)** — Flask backend with all API routes
- **`Dockerfile`** — Container build instructions
- **[`docker-compose.yml`](https://github.com/averygan/reclip/blob/main/docker-compose.yml)** — Orchestration configuration
- **[`templates/index.html`](https://github.com/averygan/reclip/blob/main/templates/index.html)** — Static single-page web interface

## Summary

- **Native script** ([`reclip.sh`](https://github.com/averygan/reclip/blob/main/reclip.sh)) is fastest for development — handles venv, dependencies, and server launch
- **Docker** provides isolation without local Python/yt-dlp installation
- **Docker Compose** adds persistence and restart policies for long-running deployments
- All methods expose the same Flask API on port 8899 with identical functionality

## Frequently Asked Questions

### What sites does ReClip support?

Any site compatible with **yt-dlp**, including YouTube, Vimeo, Twitter/X, TikTok, and 1000+ others. The [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) backend passes URLs directly to yt-dlp without site-specific filtering.

### Can I change the default port?

Yes. For native installs, export `PORT` before running [`./reclip.sh`](https://github.com/averygan/reclip/blob/main/./reclip.sh). For Docker, modify the `-p` flag or [`docker-compose.yml`](https://github.com/averygan/reclip/blob/main/docker-compose.yml) port mapping. The Flask app reads from environment variables.

### How are downloads stored?

Files save to the `downloads/` directory relative to [`app.py`](https://github.com/averygan/reclip/blob/main/app.py). In Docker, mount a volume to persist downloads outside the container: `docker run -v /host/path:/app/downloads -p 8899:8899 reclip`.

### Is authentication required?

No authentication is implemented in the base [`app.py`](https://github.com/averygan/reclip/blob/main/app.py). For internet-facing deployments, add a reverse proxy (nginx, Caddy) with basic auth or OAuth, or modify [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) to add route decorators.