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

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), 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
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 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

# macOS

brew install yt-dlp ffmpeg

# Debian/Ubuntu

sudo apt install yt-dlp ffmpeg -y

Step 2: Clone and Run

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

What the Script Does

The 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.

# Build from repository root

docker build -t reclip .

# Run with port 8899 exposed

docker run -p 8899:8899 reclip

The Dockerfile copies app.py and 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:

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:

# 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 (~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 — Native setup automation with prerequisite checking
• app.py — Flask backend with all API routes
• Dockerfile — Container build instructions
• docker-compose.yml — Orchestration configuration
• templates/index.html — Static single-page web interface

Summary

• Native script (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 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. For Docker, modify the -p flag or 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. 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. For internet-facing deployments, add a reverse proxy (nginx, Caddy) with basic auth or OAuth, or modify app.py to add route decorators.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}