How to Run ReClip Locally: Complete Setup Guide

ReClip is a lightweight Flask-based web service that wraps yt-dlp and ffmpeg to download video or audio from hundreds of sites, and you can run it locally using the provided startup script or Docker container.

ReClip provides a self-hosted alternative to online video downloaders by combining a simple web interface with powerful backend tools. To run ReClip locally, you need Python 3, yt-dlp, and ffmpeg installed on your system, then execute the automated setup script or build the Docker image. This guide covers both bare-metal and containerized deployment methods using the source code from the averygan/reclip repository.

Prerequisites for Local Installation

Before you can run ReClip locally, ensure your system has the required binaries available on your PATH.

Required System Dependencies

ReClip depends on three core components:

• Python 3 – Required for the Flask backend
• yt-dlp – Handles video extraction and downloading
• ffmpeg – Processes audio/video conversion and format selection

On macOS with Homebrew, install the dependencies with:

brew install yt-dlp ffmpeg

On Debian or Ubuntu systems, run:

sudo apt install python3 ffmpeg
pip install --user yt-dlp

Running ReClip on Bare Metal

Once the system dependencies are installed, you can deploy ReClip using the automated helper script or manually configure the Python environment.

Using the Startup Script (Recommended)

The reclip.sh script automates the entire setup process. Located in the repository root, this shell script detects required tools, creates a Python virtual environment, installs Flask and yt-dlp from requirements.txt, optionally updates yt-dlp, and launches the Flask application.

Clone the repository and execute the script:

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

The script starts the server on port 8899 by default. You should see output indicating:

ReClip is running at http://localhost:8899

Manual Setup Without the Script

If you prefer to configure the environment manually, bypass reclip.sh and set up the virtual environment yourself:

python3 -m venv venv
source venv/bin/activate
pip install flask yt-dlp
export PORT=8899
python3 app.py

In app.py, the Flask application defines routes including /api/info, /api/playlist, /api/download, /api/status/*, and /api/file/*, plus the HTML view at / served from templates/index.html.

Running ReClip with Docker

For an isolated environment that requires no local Python configuration, use the provided containerization files.

Docker Build and Run

The Dockerfile installs system packages, copies the source code, and executes reclip.sh automatically:

docker build -t reclip .
docker run -p 8899:8899 reclip

Docker Compose Deployment

Alternatively, use docker-compose.yml for a simpler one-command launch that maps port 8899:

docker-compose up --build

The container exposes the same web interface at http://localhost:8899 without modifying your host system.

Accessing and Using the Interface

After starting the server via any method, open http://localhost:8899 in your browser. The front-end UI in templates/index.html provides a single-page interface where you can:

• Paste one or more video URLs into the input field
• Select MP4 (video) or MP3 (audio) format
• Click Fetch to retrieve metadata via /api/info
• Click Download or Download All to start background jobs

The UI communicates with the Flask backend defined in app.py, which spawns background threads calling yt-dlp to download media, sanitizes filenames, and serves final files through the /api/file/* endpoints.

Programmatic API Access

You can interact with ReClip directly via HTTP requests without using the web interface.

Fetching Video Information

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

Starting a Download

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

Checking Status and Retrieving Files

Replace <JOB_ID> with the identifier returned from the download endpoint:

# Check download progress

curl http://localhost:8899/api/status/<JOB_ID>

# Download the completed file

curl -OJ http://localhost:8899/api/file/<JOB_ID>

Summary

• ReClip combines yt-dlp and ffmpeg behind a Flask web service for local video downloading.
• The reclip.sh script automates virtual environment creation, dependency installation, and server startup.
• Bare-metal deployment requires Python 3, yt-dlp, and ffmpeg installed on your system PATH.
• Docker deployment uses the provided Dockerfile or docker-compose.yml for isolated, reproducible environments.
• The web interface runs on port 8899 by default, providing routes for metadata retrieval, downloading, and file serving.
• All core logic resides in app.py, with the UI template stored in templates/index.html and Python dependencies listed in requirements.txt.

Frequently Asked Questions

What are the system requirements to run ReClip locally?

You need Python 3, yt-dlp, and ffmpeg installed and accessible on your system PATH. The reclip.sh script checks for these dependencies before starting the server. Approximately 100MB of disk space is required for the Python virtual environment and dependencies.

Can I run ReClip without using the startup script?

Yes, you can manually create a Python virtual environment, install the packages listed in requirements.txt (Flask and yt-dlp), set the PORT environment variable if desired, and execute python3 app.py directly. This bypasses the automated checks in reclip.sh but requires you to manage the virtual environment yourself.

How do I update yt-dlp when running ReClip locally?

The reclip.sh script includes an optional update mechanism for yt-dlp. When you run the script, it can check for and install the latest version of yt-dlp before starting the server. If running manually, use pip install --upgrade yt-dlp within your activated virtual environment.

Is it possible to change the default port from 8899?

Yes, set the PORT environment variable before starting the application. For bare-metal installations, run export PORT=8080 (or your preferred port) before executing ./reclip.sh or python3 app.py. For Docker deployments, modify the port mapping in your run command or docker-compose.yml file.

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