youtube-dl: a public-domain Python downloader whose newest tagged release is still 2021.12.17

Five install routes that all end in the same Python script

youtube-dl ships as one executable program, and every install route is a different way of getting that file onto your PATH. On Linux, macOS and other UNIX systems the project gives a direct download into /usr/local/bin:

sudo curl -L https://yt-dl.org/downloads/latest/youtube-dl -o /usr/local/bin/youtube-dl
sudo chmod a+rx /usr/local/bin/youtube-dl

Without curl, a recent wget does the same job:

sudo wget https://yt-dl.org/downloads/latest/youtube-dl -O /usr/local/bin/youtube-dl
sudo chmod a+rx /usr/local/bin/youtube-dl

The pip route doubles as the upgrade command, because it reinstalls over an existing copy:

sudo -H pip install --upgrade youtube-dl

On macOS you can also use a package manager, either Homebrew or MacPorts:

brew install youtube-dl

sudo port install youtube-dl

Each route has a cost. The curl and wget lines need root and write into a system directory that no package manager tracks, so removal is a manual delete. The pip line installs system wide with sudo, mixing youtube-dl into the interpreter's site-packages. Homebrew and MacPorts keep the file managed, but you get whatever version those maintainers packaged, not necessarily what is on master. For PGP signatures and other downloads, the project points to its download page at ytdl-org.github.io.

The Windows .exe breaks if you drop it into System32

Windows users get a prebuilt youtube-dl.exe from yt-dl.org instead of a Python script. The instruction that comes with it is specific: put the file in any folder on your PATH except %SYSTEMROOT%\System32, and the project explicitly says not to put it in C:\Windows\System32. That is the folder many people reach for first because it is already on PATH, so following habit here is the exact mistake the project warns against.

The .exe comes out of setup.py's py2exe branch. Running setup.py with the py2exe argument builds a console executable from ./youtube_dl/__main__.py with bundle_files set to 1, compression on, optimize at 2, and w9xpopen.exe and crypt32.dll excluded. A comment in setup.py states that this build produces an exe that needs the Microsoft Visual C++ 2008 Redistributable Package. If py2exe cannot be imported when you ask for that build, setup.py prints 'Cannot import py2exe' and exits with status 1. The consequence for anyone building their own Windows binary is a dependency on an old Python packaging tool and an old Visual C++ runtime, both of which you must source yourself.

Releases stopped at 2021.12.17 while the code kept moving

The three most recent tagged releases are 2021.05.16, 2021.06.06 and 2021.12.17. Nothing has been tagged since December 2021. Yet the repository is not archived, and the last push to the master branch happened on 2026-02-19. Those two facts together mean the project is neither dead nor actively shipping: code has landed in git for years without a matching release.

This matters because most of the install routes above fetch a release build. The -U or --update flag updates the program to the latest version, and its help text warns you to make sure you have sufficient permissions, running with sudo if needed. The pip, Homebrew and MacPorts routes likewise depend on published packages. None of them give you commits that never made it into a release.

If you need what is on master, the only route the project names is its developer instructions for checking out and working with the git repository. That puts you on an untagged snapshot with no release notes attached to it, and you will be choosing your own revision rather than trusting a version number. A last push in February 2026 also means anything that broke after that date has no fix in the repository yet.

Python 2.6 compatibility is visible all through setup.py

youtube-dl requires a Python interpreter, version 2.6, 2.7 or 3.2+, and is not tied to one operating system; it is meant to run on Unix, Windows and macOS alike. That support range explains several choices you can see in setup.py. The file opens with from __future__ import print_function so the same print calls work on Python 2 and 3. It tries to import setup and Command from setuptools, and when setuptools is missing it falls back to distutils.core and records setuptools_available as False.

The version number is not obtained by importing the package. Instead setup.py reads youtube_dl/version.py, compiles it, and execs it, which fills in __version__ without triggering any import side effects from youtube_dl itself. The package description is short: DESCRIPTION is 'YouTube video downloader' and LONG_DESCRIPTION repeats the repository tagline.

Outside the py2exe path, setup.py installs data files alongside the code: a bash completion file into etc/bash_completion.d, a fish completion into etc/fish/completions, README.txt into share/doc/youtube_dl, and a man page into share/man/man1. The command form itself stays simple: youtube-dl [OPTIONS] URL [URL...], so one call can take several URLs.

Building from source with make pulls in pandoc

The Makefile's default target builds more than the program. It produces youtube-dl, README.md, CONTRIBUTING.md, README.txt, the youtube-dl.1 man page, bash, zsh and fish completion files, and the supportedsites list. The man page step needs pandoc: the Makefile runs pandoc -v and picks markdown-smart as the input format for pandoc version 2 and plain markdown for earlier versions. A machine without pandoc cannot complete the default target.

make install copies the program with mode 755 into BINDIR, the man page into MANDIR/man1, the bash completion under SYSCONFDIR/bash_completion.d, the zsh completion into SHAREDIR/zsh/site-functions as _youtube-dl, and the fish completion under SYSCONFDIR/fish/completions. PREFIX defaults to /usr/local, with BINDIR, MANDIR and SHAREDIR derived from it, and PYTHON defaults to /usr/bin/env python. SYSCONFDIR is set to /etc only when PREFIX is /usr or /usr/local; any other prefix puts config-side files under PREFIX/etc. If you install to a custom prefix, your shell will not find those completion files unless you point it at that directory yourself. make clean removes build output and also deletes stray media files such as *.mp4, *.mkv and *.webm in the tree.

Two config files apply before your command line does

youtube-dl reads configuration files, and they can change behaviour without anything showing up in the command you typed. There is a global file at /etc/youtube-dl.conf and a per-user file at ~/.config/youtube-dl/config, or %APPDATA%/youtube-dl/config.txt on Windows. When a download behaves differently on two machines with the same command, a leftover option in one of these files is the first thing to check.

The --ignore-config flag tells youtube-dl not to read configuration files. It has a second, less obvious use: when --ignore-config is placed inside the global /etc/youtube-dl.conf, youtube-dl stops reading the user configuration in ~/.config/youtube-dl/config. An administrator can use that to stop individual users from overriding system settings.

The --config-location PATH flag points youtube-dl at a different configuration, and it accepts either the path to the config file or the directory that contains it. That makes it practical to keep separate configs for separate jobs, for example one per archive project, and select them per invocation rather than editing the shared file.

Input that is not a URL goes through --default-search

youtube-dl matches each URL against its extractors. --list-extractors prints every supported extractor and --extractor-descriptions prints a description of each, which is the direct way to see whether a site is covered by name. --force-generic-extractor skips the site-specific code and makes extraction use the generic extractor.

When you pass something that is not a full URL, --default-search PREFIX decides what happens. The default value, fixup_error, repairs broken URLs but emits an error instead of searching when it cannot. Setting auto lets youtube-dl guess, auto_warning guesses and prints a warning, and error simply throws an error. A search prefix turns the argument into a query; the help text gives gvsearch2: as an example, which downloads two videos from Google Videos for the search youtube-dl "large apple".

The consequence of the default is that a typo in a URL stops the run with an error rather than quietly downloading something you did not ask for. If you switch to auto, you trade that safety for convenience and should use auto_warning so the guess is at least reported.

Playlist failures and geo checks need explicit flags

By default a playlist run is not tolerant of failure. -i or --ignore-errors continues on download errors, for example to skip unavailable videos in a playlist. --abort-on-error does the opposite and stops downloading further videos, both in the playlist and on the command line, as soon as one error occurs. --flat-playlist only lists a playlist's videos without extracting them, a cheap way to inspect a long list before committing to it. --mark-watched and --no-mark-watched exist, but only for YouTube.

Network controls are explicit. --proxy URL takes an HTTP, HTTPS or SOCKS proxy, with SOCKS selected by scheme such as socks5://127.0.0.1:1080/, and --proxy "" forces a direct connection. --socket-timeout SECONDS, --source-address IP, -4 and -6 cover timeouts, binding and IP version.

Geo options have limits worth knowing. --geo-verification-proxy URL is used only to verify your IP address for some geo-restricted sites; the actual download still goes through --proxy, or no proxy at all. --geo-bypass works by faking an X-Forwarded-For HTTP header, which changes what you claim, not where your connection comes from, and --no-geo-bypass turns it off.

Editorial conclusion

youtube-dl suits people who want a scriptable, public-domain downloader that runs on Python 2.6, 2.7 or 3.2+ and who are comfortable reading option help and config files. It is a poor fit for anyone expecting fresh binaries: the newest tagged release is 2021.12.17 and the last push to master was on 2026-02-19, so before relying on it, check whether the version you install actually handles the sites you need, and decide whether you are prepared to run it from a git checkout instead of a release build.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes