# How to Run ReClip Locally: Complete Setup Guide > Learn how to run ReClip locally with this complete setup guide. Easily download videos and audio from hundreds of sites using this lightweight Flask web service. - Repository: [Avery Gan/reclip](https://github.com/averygan/reclip) - Tags: how-to-guide - Published: 2026-09-05 --- **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: ```bash brew install yt-dlp ffmpeg ``` On Debian or Ubuntu systems, run: ```bash 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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/requirements.txt), optionally updates yt-dlp, and launches the Flask application. Clone the repository and execute the script: ```bash 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`](https://github.com/averygan/reclip/blob/main/reclip.sh) and set up the virtual environment yourself: ```bash python3 -m venv venv source venv/bin/activate pip install flask yt-dlp export PORT=8899 python3 app.py ``` In [`app.py`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/reclip.sh) automatically: ```bash docker build -t reclip . docker run -p 8899:8899 reclip ``` ### Docker Compose Deployment Alternatively, use [`docker-compose.yml`](https://github.com/averygan/reclip/blob/main/docker-compose.yml) for a simpler one-command launch that maps port 8899: ```bash 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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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 ```bash 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 ```bash 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 `` with the identifier returned from the download endpoint: ```bash # Check download progress curl http://localhost:8899/api/status/ # Download the completed file curl -OJ http://localhost:8899/api/file/ ``` ## Summary - **ReClip** combines yt-dlp and ffmpeg behind a Flask web service for local video downloading. - The [`reclip.sh`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/app.py), with the UI template stored in [`templates/index.html`](https://github.com/averygan/reclip/blob/main/templates/index.html) and Python dependencies listed in [`requirements.txt`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/reclip.sh) but requires you to manage the virtual environment yourself. ### How do I update yt-dlp when running ReClip locally? The [`reclip.sh`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/./reclip.sh) or `python3 app.py`. For Docker deployments, modify the port mapping in your run command or [`docker-compose.yml`](https://github.com/averygan/reclip/blob/main/docker-compose.yml) file.