Lux: a Go downloader that splits extraction from transfer
👾 Fast and simple video download library and CLI tool written in Go
At a glance
- What is it?
- Lux is an MIT-licensed Go CLI and library that resolves a video URL into a list of streams, then fetches them. It is convenient for scripted archival and awkward anywhere you need a guarantee about format support or long-term maintenance.
- Who is it for?
- 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, HLS or DASH handling, 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.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 170 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
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 is the reason Lux stays small. It does not need to guess which quality you want, and it does not need to re-resolve the page if you already know the identifier. It also 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 and no configuration file, 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 topics list names bilibili, iqiyi, qq, tumblr, youku and youtube among others. 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. The README truncates before listing them all, so the full flag set is not verifiable from the README.
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. The README names these but the supplied text does not show their flag names or semantics, so check lux --help 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 silently 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. Nothing in the README describes a machine-readable output format for the extraction stage, which makes that check harder than it should be.
How this differs from yt-dlp
The obvious alternative is yt-dlp, which the README's Similar projects section points at. 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, and there is no configuration file or database to migrate. 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, HLS or DASH handling, 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.
Community notes