FAQ

Frequently asked questions about fetchit — a terminal video downloader.

General

What is fetchit?

fetchit is a terminal-based video downloader with a text-based user interface (TUI). It wraps yt-dlp to download videos and audio from hundreds of sites. You give it a URL, pick a format from the interactive TUI, and it handles the rest.

What sites does it support?

fetchit supports everything yt-dlp supports — that's over 1,700 sites including YouTube, Vimeo, Twitch, Twitter/X, Instagram, TikTok, Reddit, Bilibili, SoundCloud, Bandcamp, Facebook, Dailymotion, and many more. See the full list on the yt-dlp supported sites page.

Is it free?

Yes. fetchit is free and open source under the MIT license. You can use it, modify it, and distribute it freely. There are no paid tiers, subscriptions, or hidden charges.

Do I need an API key?

No. fetchit and yt-dlp work by extracting media URLs directly from web pages, not through official APIs. You don't need any API keys, tokens, or accounts to download.

Installation

How do I install it?

See the installation guide for platform-specific instructions. On most systems, you can use one of these methods:

# macOS (Homebrew)
brew install fetchit

# Windows (Scoop)
scoop bucket add fetchit https://github.com/your-org/scoop-bucket
scoop install fetchit

# Linux (curl binary)
curl -fsSL https://github.com/your-org/fetchit/releases/latest/download/fetchit-linux-x86_64.tar.gz | tar xz
sudo mv fetchit /usr/local/bin/

# Or build from source
cargo install fetchit

Why is the binary so large (~100 MB)?

The binary bundles a private copy of Python and yt-dlp so you don't have to install them separately. This makes fetchit self-contained and ensures the yt-dlp version is always compatible. Without this bundling, you'd need to install Python and yt-dlp manually, and version mismatches would cause frequent breakage. The trade-off is a larger binary in exchange for a zero-friction install.

How do I update?

fetchit checks for updates on startup and prompts you when a new version is available. You can also update manually:

# macOS
brew upgrade fetchit

# Windows
scoop update fetchit

# Linux — re-download the binary
# or if built from source
cargo install fetchit --force

How do I uninstall?

# macOS
brew uninstall fetchit

# Windows
scoop uninstall fetchit

# Linux
sudo rm /usr/local/bin/fetchit

# Remove config and cache
rm -rf ~/.config/fetchit ~/.cache/fetchit

On Windows, the config is at %APPDATA%\fetchit and cache at %LOCALAPPDATA%\fetchit.

Usage

How do I download a video?

The simplest way is to pass a URL directly:

fetchit "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

This opens the TUI where you can choose the format and quality. To skip the TUI and use the best quality automatically:

fetchit "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --auto

See the getting started guide for more details.

How do I get just the audio?

fetchit "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --audio

# Specify a format (default is mp3)
fetchit "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --audio --audio-format flac

# Or use the TUI and select audio-only from the format list
fetchit "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Audio-only mode extracts the best available audio stream and converts it to your chosen format.

How do I download a playlist?

fetchit detects playlists automatically. Pass the playlist URL and it will list all videos:

# Download all videos in a playlist
fetchit "https://www.youtube.com/playlist?list=PL..."

# Download a range of videos
fetchit "https://www.youtube.com/playlist?list=PL..." --range 1-5

# Download every Nth video
fetchit "https://www.youtube.com/playlist?list=PL..." --range 1-10:2

You can also use --audio with playlists to download all videos as audio files.

Why is it asking me to download yt-dlp?

The first time you run fetchit (or after an update that bumps the yt-dlp version), fetchit needs to extract the bundled yt-dlp to your system. This is a one-time extraction — subsequent launches use the cached version. It may also ask if you're using a self-contained binary that doesn't bundle yt-dlp (e.g., if you built from source without the bundle feature).

Troubleshooting

YouTube says "Sign in to confirm" — what do I do?

YouTube occasionally rate-limits downloads by requiring a sign-in. Try these solutions in order:

1. Use cookies — export your YouTube cookies and pass them to fetchit (see How do I pass cookies? below).
2. Update yt-dlp — run fetchit --update-yt-dlp to get the latest extraction logic.
3. Use a different IP — YouTube ratelimits by IP. Try a VPN or different network.
4. Wait — the rate limit usually expires after a few hours.

Downloads are slow — why?

Several factors can affect download speed:

• Your internet connection — run a speed test to check your baseline.
• Source server throttling — YouTube and other sites limit download speeds to prevent abuse. This is normal and varies by region.
• Concurrent downloads — use fetchit --concurrent-downloads 3 to download multiple streams at once.
• Rate limiting — see the "Sign in to confirm" section above for rate-limit fixes.
• ISP throttling — some ISPs throttle video streaming. A VPN may help.

The TUI doesn't look right in my terminal

fetchit's TUI uses terminal graphics (sixel or Kitty protocol) for thumbnails and Unicode box-drawing characters for the interface. If things look off:

• Use a modern terminal emulator — Kitty, Alacritty, Windows Terminal, iTerm2, or Ghostty.
• Set your terminal font to a Nerd Font (e.g., JetBrains Mono Nerd Font).
• Run fetchit --no-thumbnails to disable thumbnail rendering.
• Run fetchit --no-color if colors are garbled.
• Ensure $TERM is set correctly (e.g., xterm-256color,kitty, or alacritty).

How do I pass cookies?

To authenticate with sites that require login (e.g., YouTube premium, private Instagram profiles), export your browser cookies and pass them to fetchit:

# Automatically extract cookies from your browser (easiest)
fetchit "https://www.youtube.com/watch?v=..." --cookies-from-browser chrome

# Or use a cookies.txt file (export with a browser extension)
fetchit "https://www.youtube.com/watch?v=..." --cookies cookies.txt

Supported browsers: chrome, firefox, brave,edge, opera, safari, and vivaldi.

Technical

How does fetchit work under the hood?

At a high level, fetchit follows these steps for every download:

1. URL parsing — fetchit validates the URL and normalises it.
2. Site detection — it identifies which site the URL belongs to and dispatches to the correct extractor.
3. Metadata extraction — yt-dlp fetches the page, extracts available formats, resolutions, codecs, thumbnails, and metadata.
4. TUI rendering — fetchit presents the available formats in an interactive list with thumbnails, file sizes, and quality labels.
5. Selection & download — once you pick a format, fetchit invokes yt-dlp to stream the media to disk, showing a progress bar with ETA and speed.
6. Post-processing — if requested, it converts audio to the target format, embeds metadata, and writes thumbnails.

fetchit itself is a thin Rust wrapper around yt-dlp. The core download engine is entirely yt-dlp — fetchit provides the interactive user experience on top.

What is yt-dlp?

yt-dlp is a command-line program for downloading videos from YouTube and over 1,700 other websites. It's a feature-rich fork of the original youtube-dl. yt-dlp handles all the complex extraction logic, format negotiation, and downloading — fetchit wraps it in a user-friendly TUI so you don't have to memorise yt-dlp's extensive command-line flags.

You can use yt-dlp directly if you prefer — fetchit is entirely optional.

Is my privacy protected?

fetchit does not phone home. There are no telemetry, analytics, or usage tracking features. The only network requests fetchit makes are:

• Checking for updates (you can disable this with fetchit --no-update-check).
• Fetching video metadata and streams from the URLs you provide.
• Downloading the bundled yt-dlp on first launch (from GitHub releases).

Your download history is stored locally in ~/.cache/fetchit/history.json and is never sent anywhere. You can clear it at any time.

Can I use it in scripts?

Yes. Pass --auto to skip the TUI and use smart defaults. This makes fetchit suitable for cron jobs, shell scripts, and automation pipelines:

#!/bin/bash
# Download the best quality video automatically
fetchit "https://www.youtube.com/watch?v=..." --auto

# Download audio-only to a specific directory
fetchit "https://www.youtube.com/watch?v=..." --audio --output-dir ~/Music --auto

# Download a playlist, videos 1-5, best quality
fetchit "https://youtube.com/playlist?list=PL..." --range 1-5 --auto

# Quiet mode (no output at all)
fetchit "https://www.youtube.com/watch?v=..." --auto --quiet

fetchit exits with a non-zero code on failure, so you can handle errors in your scripts.

Support

How do I report a bug?

Open an issue on the GitHub issue tracker. Please include:

• Your operating system and terminal emulator.
• The output of fetchit --version.
• The exact command you ran.
• The full error output (use --verbose for detailed logs).
• A sample URL if possible (you can obfuscate personal details).

# Run with verbose logging to help debugging
fetchit "https://www.youtube.com/watch?v=..." --verbose 2>&1 | tee fetchit-debug.log

Where do I request features?

Feature requests are welcome on the GitHub Discussions page. Before posting, please search existing discussions and issues to avoid duplicates. When requesting, describe the problem you're trying to solve rather than just suggesting a specific solution — this helps us find the best approach.