What yt-dlp does and why you'd use it

yt-dlp is a command-line tool that downloads videos from YouTube and hundreds of other video sites and saves them as MP4 files (or other formats) to your computer. It's the maintained successor to youtube-dl, which means it gets regular updates to keep working as websites change their code.

You run yt-dlp by typing commands into your terminal or command prompt rather than clicking buttons in an app. This sounds more complicated than it is — you'll type one line, press Enter, and the video downloads. The payoff is that yt-dlp works reliably on Windows, Mac, and Linux, handles videos that other downloaders can't touch, and lets you download entire playlists or channels in one command.

The tool itself is free and open-source, meaning anyone can read the code and contribute fixes. You're responsible for respecting copyright and the terms of service of the site you're downloading from — yt-dlp is just the mechanism.

Key Takeaways

  • yt-dlp requires Python to run, which you install first, then install yt-dlp itself using a single command.
  • The basic download command is yt-dlp -f "best[ext=mp4]" [URL], where you replace [URL] with the video link.
  • Videos save to your Downloads folder by default, but you can change where they go by adding a path to the command.
  • yt-dlp can download entire playlists or channels at once, which saves time if you need multiple videos.
  • If a download fails, the most common fixes are updating yt-dlp, checking your internet connection, or trying a different format option.

Install Python first, then yt-dlp

yt-dlp runs on Python, a programming language that your computer needs to have installed. Most Macs come with Python already, but Windows usually doesn't. Check whether you have it by opening your terminal (Mac) or command prompt (Windows) and typing python --version. If you see a version number, you're ready to move to the next step. If you get an error, download Python from python.org, run the installer, and make sure to check the box that says "Add Python to PATH" during setup.

Once Python is installed, install yt-dlp by opening your terminal or command prompt and typing this single line:

pip install yt-dlp

Press Enter and wait for the installation to finish. You'll see text scrolling past — that's normal. When it's done, you're ready to download videos.

Download a single video as MP4

Open your terminal or command prompt and type this command, replacing the URL with the actual video link:

yt-dlp -f "best[ext=mp4]" https://www.youtube.com/watch?v=dQw4w9WgXcQ

The -f "best[ext=mp4]" part tells yt-dlp to download the highest quality version available and save it as an MP4 file. Press Enter and the download starts. You'll see progress updates in the terminal showing the download percentage and speed. The video saves to your Downloads folder by default.

If you want the video to save somewhere else, add this to the command before the URL:

-o "~/Desktop/%(title)s.%(ext)s"

This saves the video to your Desktop with its original title. Replace "Desktop" with any folder path you want. The %(title)s part automatically uses the video's title as the filename, and %(ext)s adds the file extension (mp4, etc.).

Download playlists or entire channels

If you need multiple videos, yt-dlp can grab them all at once. For a YouTube playlist, use this command:

yt-dlp -f "best[ext=mp4]" https://www.youtube.com/playlist?list=PLxxxxxx

Replace the URL with your playlist link. yt-dlp downloads every video in the playlist and saves them to your Downloads folder with numbered filenames so they stay in order.

For an entire channel, use the channel URL instead. yt-dlp will download all public videos from that creator. This can take a long time and use a lot of storage, so you might want to add a limit. To download only the 10 most recent videos from a channel, add --max-downloads 10 to your command.

Troubleshoot downloads that fail or get stuck

If a download fails, the first thing to try is updating yt-dlp, because websites change their code frequently and yt-dlp needs updates to keep working. Type this command:

pip install --upgrade yt-dlp

Then try the download again. If it still fails, check that your internet connection is stable — a weak connection can interrupt large downloads. Try downloading a shorter video first to see if the problem is specific to that video or a general issue.

If you get an error message mentioning "format" or "no video found", the video might not be available in MP4 format. Try removing the format requirement and let yt-dlp choose the best available format:

yt-dlp https://www.youtube.com/watch?v=dQw4w9WgXcQ

This downloads the video in whatever format works, which might be MKV or WebM instead of MP4. You can convert it afterward if you need MP4 specifically.

Common options to customize your downloads

yt-dlp has dozens of options, but these are the ones most people need. Add any of these to your command before the URL:

--audio-only downloads just the audio as an MP3 file instead of the full video. Useful for music or podcasts.

--subtitle-langs en downloads English subtitles along with the video. Replace "en" with any language code (es for Spanish, fr for French, etc.).

--date-after 20240101 downloads only videos posted after January 1, 2024. Use this when downloading a channel to skip old content.

-o "%(uploader)s/%(title)s.%(ext)s" organizes downloads into folders by the video creator's name, which helps when downloading from multiple channels.

Frequently Asked Questions

Can I download videos from sites other than YouTube?

Yes. yt-dlp works with hundreds of video sites including Vimeo, TikTok, Instagram, Twitch, and many others. Use the same command with the video URL from any supported site. Check the yt-dlp documentation for a full list of supported sites, though new ones are added regularly.

Why does my download stop partway through?

Network interruptions are the most common cause. If you're on WiFi, try moving closer to your router or switching to a wired connection if possible. For very large files, add --fragment-retries 10 to your command so yt-dlp retries failed parts instead of giving up.

What's the difference between MP4 and the other formats yt-dlp offers?

MP4 is the most compatible format — it plays on almost every device and media player. MKV and WebM offer better quality but don't play on all devices. Stick with MP4 unless you have a specific reason to use something else.

Can I pause a download and resume it later?

yt-dlp doesn't have a built-in pause feature, but if your download gets interrupted, running the same command again will usually resume from where it stopped rather than starting over. If it restarts from the beginning, add --continue to force resuming.

Do I need to update yt-dlp regularly?

Yes. Websites update their code frequently, and yt-dlp needs updates to keep working. Run pip install --upgrade yt-dlp once a month or whenever a download fails for no obvious reason. Updates are quick and don't affect your existing videos.