Skip to main content
This quickstart guide will help you get OfflineTube running on your local machine quickly. You’ll install dependencies, start both the frontend and backend servers, and download your first video.

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js 20+

JavaScript runtime for the frontend

Python 3.10+

Backend API runtime environment

ffmpeg

Media processing toolkit (must be in PATH)
Verify ffmpeg is installed by running ffmpeg -version and ffprobe -version in your terminal.

​
Installation

1

Clone or navigate to the project

Navigate to your OfflineTube source directory:
cd /path/to/offlinetube
2

Install frontend dependencies

Install the Node.js packages using npm:
npm install
This will install Next.js, React, and all required frontend dependencies from package.json.
3

Set up the backend

Create a Python virtual environment and install backend dependencies:
cd mini-services/offlinetube-api
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
On Windows, use .venv\Scripts\activate instead of source .venv/bin/activate
4

Start the backend server

From the mini-services/offlinetube-api directory with your virtual environment activated:
python main.py
The backend will start on http://0.0.0.0:8001. You should see:
INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)
5

Start the frontend server

Open a new terminal window, navigate to the project root, and start the frontend:
npm run dev
The frontend will start on http://localhost:3000.
6

Access the application

Open your browser and navigate to:
http://localhost:3000
You should see the OfflineTube interface ready to use.

​
Your first download

Now that OfflineTube is running, let’s download your first video:
1

Search for content

Use the search bar in the OfflineTube interface to find a video, or browse trending content.
2

Select quality and format

Click on a video to view its details. You’ll see options to:
  • Choose between video or audio-only download
  • Select quality (e.g., 720p, 1080p, 480p)
  • Pick specific formats if available
3

Start the download

Click the download button to begin. You’ll see:
  • Real-time progress percentage
  • Download speed
  • Estimated time remaining
  • File size information
4

Watch offline

Once complete, your video appears in the offline library. Click to play it locally with the built-in player.
Downloaded files are stored in mini-services/offlinetube-api/downloads/

​
Quick tips

Network access: The frontend automatically detects the backend URL. If accessing from another device on your LAN, visit http://YOUR_IP:3000 and it will connect to http://YOUR_IP:8001 automatically.
Backend must run first: Always start the backend (port 8001) before the frontend (port 3000) to ensure proper API connectivity.

​
Troubleshooting

If you encounter issues:
  • “Failed to fetch” errors: Verify the backend is running on port 8001 and check firewall settings
  • FFmpeg errors: Ensure ffmpeg and ffprobe are installed and available in your system PATH
  • No thumbnails: Thumbnails use remote fallbacks automatically, but local caching may take a moment
  • Missing audio: The backend validates audio tracks; if a download lacks audio, it will be marked as an error

​
Next steps

Detailed installation

Learn about environment variables, system requirements, and advanced configuration

API reference

Explore the backend API endpoints for integration and automation

Build docs developers (and LLMs) love

Get started for freeTalk to us