Guide · Open source
How to use Lux: download videos from the command line
Updated · written with AI from the project's own documentation and checked against our catalogue data
Lux is a free, open-source video downloader that runs in the terminal. You give it a web page address, it finds the video streams on that page, and it saves them to your computer. This guide shows you how to install it, list the available qualities, download a chosen one, and handle playlists and batches of links.
Luxiawia002/lux · ★ 31.8k · MIT Install options & downloads Quick start
- 1Install FFmpeg. Install FFmpeg separately, since Lux needs it for merging audio and video.
- 2Install Lux. Run go install github.com/iawia002/lux@latest, or brew install lux on macOS.
- 3List available qualities. Run lux -i with the video page URL to see each stream and its size.
- 4Download a chosen stream. Run lux -f with the stream ID and the same URL.
- 5Download a playlist or batch. Add -p for a playlist, or use -F with a text file of URLs, and narrow with -items if needed.
- 6Resume if interrupted. Rerun the same command after Ctrl+C to continue from the .download file.
Install Lux with go install or Homebrew
Lux is written in Go. The README lists FFmpeg as a required separate dependency, used for the final file merge. It does not affect the download itself. Install FFmpeg first, then install Lux using one of the methods below.
On macOS you can use Homebrew. Other options listed in the README include the AUR package for Arch Linux, xbps-install for Void Linux, Scoop, Chocolatey and Cask on Windows, and downloading a binary from the Releases page.
- Go users: run go install to build Lux from source
- macOS users: run brew install lux (Homebrew is listed as macOS only)
- Windows users: Scoop or Chocolatey are listed in the README
$ go install github.com/iawia002/lux@latestDownload a video from a page URL
Run lux followed by the page address in quotes. Lux shows the site, title and available streams, then downloads the chosen stream while showing progress.
To see every quality without downloading, add the -i option. Each stream is listed with its quality and file size, plus a line showing the -f command to use.
- Use lux -i URL to list all available qualities without downloading
- Use lux -f STREAM URL to download a specific stream from that list
$ lux -i "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
$ lux -f 137 "https://www.youtube.com/watch?v=dQw4w9WgXcQ"Download a playlist or a batch of links
The -p option downloads an entire playlist instead of a single video. You can narrow the range with -start, -end or -items, where -items accepts comma-separated values and ranges such as 1,5,6,8-10.
To download several URLs, list them after the command, and they download one by one. To read URLs from a file, use -F with the path to a text file. The same -start, -end and -items options apply to file lines.
- -p downloads a whole playlist
- -items 1,5,6,8-10 picks specific playlist entries
- -F path/to/file reads URLs from a file, one per line in the source's example
- -eto (bilibili playlists only) leaves the playlist title out of each episode file name
$ lux -p -items 1,5,6,8-10 "PLAYLIST_URL"
$ lux -F ~/Desktop/u.txtResume, retry and set the output location
Press Ctrl+C to interrupt a download. Lux keeps a temporary .download file in the output directory. Run lux again with the same arguments and the download resumes from the last session.
If a download fails, Lux retries automatically. The -retry option sets the number of attempts, and the README gives a default of 100. You can also specify the output path and file name with the options in the README's Filesystem section.
- Interrupt with Ctrl+C; rerun the same command to resume
- -retry sets retry times (default 100 per the README)
Options for cookies, proxies and other needs
The README covers more advanced cases in separate sections: cookies through the -c option when a site requires them, proxy settings, multi-threaded downloads, a specified referrer, debug mode, reusing extracted data, and subtitles. The full option list is grouped into Download, Network, Playlist, Filesystem, Subtitle, Youku and aria2 categories.
Run lux with the help flag or check the README's Options section for exact flag names, since this guide only covers the options quoted in the source.
- Cookies: -c option
- Subtitles, Network, Filesystem: see the README Options section
Know the limits before you start
Lux works on supported sites. For a URL it does not support, it tries to download the address directly as a file, which works for direct file links such as images but is not site extraction. The README notes that Lux is command-line only, with no graphical interface.
Lux does not ship FFmpeg, so you need it installed separately if you want merged audio and video output.
- Command line only; no GUI is described in the README
- Unsupported sites are attempted as direct file downloads only
- FFmpeg must be installed separately for merging
What people use it for
- Save a video from a supported site to a local file for offline viewing
- Compare file sizes across qualities before choosing one with -f
- Download selected episodes from a bilibili playlist using -items
- Batch-download links listed in a text file using -F
- Reuse Lux's video extraction logic as a Go library in your own program
Frequently asked questions
Is Lux free and open source?
Yes. The repository is licensed under MIT, as listed in the project summary. You can read, modify and reuse the code under that licence.
How do I install Lux?
Install FFmpeg first, then run go install github.com/iawia002/lux@latest. On macOS you can run brew install lux. The README also lists package options for Arch, Void, Scoop, Chocolatey and Cask, and binaries on the Releases page.
Do I need FFmpeg to use Lux?
FFmpeg is listed as a required dependency that must be installed separately. The README says it does not affect the download itself, only the final merge of audio and video.
How do I choose a video quality?
Run lux -i with the URL to list all streams, then run lux -f with the stream ID you want. Each listing shows the quality and the file size.
Why won't Lux download my video from a site?
Lux supports a specific list of sites. For other URLs, it only tries a direct file download, so a page that is not on the supported list may fail. Check the Supported Sites section of the README.
What is the difference between Lux and yt-dlp?
Both are command-line downloaders. The README does not compare them directly, so check each project's documentation for site coverage and features before choosing. Lux is distinct in being written in Go and usable as a library.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Lux suits people who are comfortable in a terminal and want to save videos from supported sites, pick a quality, or batch-download playlists. It is a poor fit if you want a graphical app, need a site outside the supported list, or cannot install FFmpeg for merged output; in those cases, compare it with alternatives such as yt-dlp or you-get.
Install options & downloads