Lux: a Go downloader that splits extraction from transfer

The two-stage model behind every Lux command

Lux does not treat a video URL as a single file. It treats it as a page containing one or more streams, and it separates the job of finding those streams from the job of downloading them. Running lux with no flags performs both stages in sequence: extract, then fetch the default stream. Running lux -i stops after extraction and prints what was found. The README shows the output shape for a YouTube URL, listing entries such as [248] with a quality line like 1080p video/webm; codecs="vp9" and a byte size, followed by a hint: # download with: lux -f 248 ... That printed hint is the interface. The extractor hands you stream identifiers, and -f selects one.

This split means the extractor is the part that breaks when a site changes its player, while the downloader keeps working. For a tool with no homepage, that is a sensible place to put the complexity.

What the supported site list actually commits you to

The README carries a Supported Sites section and a Known issues section with entries for 优酷 (Youku) and 西瓜/头条视频 (Xigua/Toutiao). Those two sections together are the honest scope statement. Lux is built around site-specific extractors, and the repository has an extractors/ directory. Each extractor encodes assumptions about one site's page structure and API responses.

That design has a direct consequence for anyone evaluating it. Coverage is not uniform. A site can be listed and still be listed under known issues, which is exactly what the README does for Youku and Xigua. The documentation does not quantify how often extractors break or how quickly they are fixed. The repository metadata shows a last push in March 2026 but the most recent listed release is v0.24.1 from May 2024, so extractor fixes may land on master without a tagged version. If you install from a package manager, you are probably getting the tagged release, not master.

Installing Lux and the FFmpeg dependency that is not optional in practice

The README lists one prerequisite: FFmpeg, with a note that it does not affect the download, only the final file merge. That distinction matters. Lux can fetch a stream without FFmpeg, but when a site serves video and audio separately, the merge step is what produces a playable file. Treat FFmpeg as required unless you only ever download single-file resources.

Installation paths are broad. The Go route is go install github.com/iawia002/lux@latest. macOS users can run brew install lux. Arch has an AUR package named lux-dl, Void uses xbps-install -S lux, Windows has scoop install lux and choco install lux, and there is a cask install github.com/iawia002/lux for Windows, macOS and Linux. Basic usage is lux [OPTIONS] URL [URL...], and multiple URLs in one invocation are supported.

Useful flags visible in the README include -p for playlists, -start, -end and -items for playlist ranges (the last accepts values like 1,5,6,8-10), -f for stream selection, -i for inspection only, and -eto for bilibili playlist file naming. There are also options grouped under Download, Network, Playlist, Filesystem, Subtitle, Youku and aria2 headings.

Cookies, proxies, referrers and the fallback path

Several flags address the parts of downloading that are not about bytes. Cookies and proxy options exist, as does a flag to use a specified Referrer, which the README lists as its own section. These are the levers you reach for when an extractor returns nothing or returns a 403, because many sites gate media URLs on session state or on the referring page.

Lux also has a fallback behaviour worth understanding. Given a URL it does not recognise, it prints a message saying it does not support the URL right now but will try to download it directly, then treats the response as a generic resource. The README example fetches a JPEG and reports Type: image/jpeg with a [default] stream. So the tool degrades to a plain HTTP client rather than failing outright. That is convenient for one-off assets and misleading for video: a direct download of a video page URL will often return HTML, not media.

Other operational features listed are resume, auto retry, multi-thread downloading, short link handling (with a bilibili subsection), specifying the output path and name, a debug mode, and reusing extracted data so a second run can skip extraction. Check lux --help for their flag names before relying on them.

Where Lux is the wrong tool

The clearest limitation is extractor fragility. Lux resolves streams by understanding each site, and sites change. When an extractor drifts, -i returns nothing useful and the download never starts. There is no plugin interface described in the README for adding a site without editing the Go source, so fixing coverage means either waiting or building from master yourself.

The second limitation is release cadence versus repository activity. The newest release listed is v0.24.1 from 2024-05-06, and the previous two are v0.24.0 and v0.23.0 from earlier in 2024. The repository was pushed in March 2026. That gap means packaged installs may lag the code that actually fixes a broken extractor, and it means you cannot assume a version number reflects current site support.

The third is the fallback path. Because Lux switches to a direct download for unrecognised URLs, a broken extractor can look like a working command that produces an HTML file. If you script Lux, check the output rather than the exit status.

How this differs from yt-dlp

The obvious alternative is yt-dlp. The difference is architectural. yt-dlp ships a large collection of extractors as a plugin-style tree and is distributed primarily as a Python program, with frequent releases that carry extractor fixes. Lux compiles extractors into a single Go binary, which is easy to drop onto a machine with no runtime, and which you can import as a library since the project is described as both a library and a CLI.

If you want the widest site coverage and the fastest turnaround on breakage, yt-dlp is the safer default. If you want a small static binary, a Go API, and you only care about a handful of sites, Lux's model is cleaner. The trade is coverage and fix latency against deployment simplicity. Neither the README nor the repository metadata lets you quantify that trade for your specific sites; only a test run does.

Licence, upgrades and what to check before you commit

Lux is MIT licensed. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained, but this is a description of the licence text, not legal advice; read the LICENSE file in the repository and consult counsel if the distinction matters to you. MIT also means you can vendor the code and patch an extractor yourself, which is the practical escape hatch when a site breaks and no release is coming.

Upgrade cost is low in the ordinary case: the install commands are one-liners,. The cost that is not low is verification. Because extractors are the fragile part and because the fallback path can mask failure, every upgrade needs a smoke test against the sites you actually use. Run lux -i on one URL per site and confirm you get stream entries with sizes rather than the universal-download message. That single command is the check that separates a working upgrade from a silent regression.

Editorial conclusion

Adopt Lux if you want a single static Go binary that turns a supported site URL into numbered streams you can select with -f, and you are comfortable installing FFmpeg separately for merges. Do not adopt it if you need broad site coverage or a project with recent tagged releases; the latest listed release is v0.24.1 from May 2024, while the repository shows a push in March 2026. Verify first that your target site appears in the supported list, then run lux -i on one URL to confirm the extractor still returns streams before wiring it into anything automated.

Frequently asked questions

Official sources

1. iawia002/lux on GitHub
2. Issues
3. License: MIT
4. README
5. Releases