iawia002/lux: a Go video downloader for YouTube, bilibili and other sites

What Lux actually does, and who ends up using it

Lux solves one problem: given a page URL, find the media stream behind it and save that stream to disk. The README describes it as a "fast and simple video downloader built with Go", and the repository is organised as a Go module (github.com/iawia002/lux) with an app/ entry point, an extractors/ directory for per-site logic, a downloader/ package, and a parser/ package. That layout tells you the intended audience: people who want a command they can put in a script, and Go developers who want to import the extraction and download machinery rather than shell out to a binary.

The tool is not a browser extension and not a service. It runs where you run it, resolves the URL, and writes the file locally. The README's supported-sites list is the boundary of what it can do well; anything outside that list falls back to a direct download attempt, which the README illustrates with an image URL and the message that Lux "doesn't support this URL right now, but it will try to download it directly". That fallback is genuinely useful for plain files and useless for anything that needs page parsing or authentication.

How extraction and download work in Lux

The flow is extract, select, fetch, merge. Lux sends a request to the URL, an extractor for that site parses the response, and the result is a list of streams, each with a quality label, a MIME type, a byte size and an identifier. The README's YouTube example shows the shape of that output: a Site line, a Title, a Type, then one or more Stream entries, each with Quality, Size and a suggestion such as "download with: lux -f 248".

The -i flag prints that list without downloading, which is the single most useful thing to run first, because it tells you whether the site is recognised and which stream IDs exist. Selection is by ID through -f. For sites that serve video and audio as separate tracks, FFmpeg is the component that joins them: the README states plainly that FFmpeg "does not affect the download, only affects the final file merge", so a missing FFmpeg gives you a download that never becomes a playable file rather than an immediate error.

Beyond a single URL, Lux accepts multiple URLs on one command line, downloads playlists with -p, and can resume, retry automatically, use cookies, go through a proxy, and run multi-threaded. It can also reuse previously extracted data, which matters when you are re-downloading the same item at a different quality and do not want to hit the site's extraction path again.

Installing Lux and downloading your first video

Install FFmpeg first if you ever expect separate audio and video tracks. Then pick one installation path. Go users can install straight from the module, and the README gives this command:

go install github.com/iawia002/lux@latest

macOS users have a Homebrew formula, Windows users have Scoop and Chocolatey packages, and Arch, Void Linux and Cask users have their respective packages. The README also points at the Releases page for prebuilt binaries if you would rather not build.

Before downloading anything, inspect the available streams. The README's own example is this:

lux -i "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

You should see a Site block, a Title, and a numbered list of streams with quality, codec and size. If that block appears, extraction worked. If Lux prints that it does not support the URL, it will fall back to a direct download, which only makes sense for plain file URLs.

To fetch a specific stream, pass its ID from the -i output:

lux -f 248 "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

A progress bar runs while the file is written. For a playlist, add -p and optionally narrow the range:

lux -p -start 1 -end 5 "https://www.bilibili.com/bangumi/play/ep198061"

The -start, -end and -items options control which entries are pulled; -items takes comma-separated values and ranges such as 1,5,6,8-10. For sites that require a signed-in session, -c takes cookies, and the README documents a proxy option for routing traffic elsewhere.

Where Lux breaks, and when it is the wrong tool

The most important limitation is that Lux depends on site behaviour it does not control. Extractors are per-site code, and the README keeps a Known issues section with entries for 优酷 and 西瓜/头条视频, which is a direct admission that some supported sites do not work reliably. When a site changes its player, the extractor has to change with it.

FFmpeg being optional for the download but required for the merge is a second trap. A script that checks only the exit status of the download step can end up with a directory of separate tracks and no error. Test your pipeline with FFmpeg absent once, so you know what failure looks like.

Third, Lux is not a way around access control. It has no DRM support, and the README's answer to restricted content is cookies, not decryption. If a video is gated by a login you do not have, or by DRM, Lux is the wrong tool. The same applies to sites outside the supported list that do not expose a plain file URL: the direct-download fallback will fetch HTML and save it under a media-looking name.

Finally, release cadence is not something to assume. The most recent release listed in the repository is v0.24.1 from 2024-05-06, while the last push to the default branch was on 2026-03-29. Commits continue; tagged releases are much rarer, so if you pin versions, expect to pin to a tag that is older than the code.

Lux against yt-dlp and gallery-dl

The realistic alternative for most readers is yt-dlp. The difference in approach is where the site knowledge lives. Lux ships extractors compiled into a single Go binary and depends on the kkdai/youtube library for YouTube; yt-dlp is a Python program whose extractors are updated independently and far more often, and it covers a much wider set of sites. If your problem is "this one site stopped working", yt-dlp is usually the faster fix. If your problem is "I want this inside a Go program or a small self-contained binary with no Python runtime", Lux is the better fit, and its library shape is the reason to choose it.

For image-heavy sites, gallery-dl is the closer comparison, since it targets galleries and collections rather than video streams with quality selection. Lux's direct-download fallback will fetch a single image URL, as the README demonstrates, but it is not built to walk a gallery.

A fair summary: Lux trades breadth and update speed for a small, typed, embeddable Go implementation. That trade is worth making when the sites you need are on the supported list and you value the binary; it is a poor trade when you are chasing a long tail of sites.

Licence, maintenance and the cost of upgrading

Lux is MIT licensed, which is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and permission notice are retained. That is the whole of the grant; the repository's LICENSE file is the authority, and nothing here is legal advice.

Upgrade cost is mostly extractor churn. Because the site list is compiled in, a new site or a fixed extractor arrives with a new build, not with a config change. If you install via go install, upgrading means re-running the install command; if you use a package manager, it means whatever that manager does. The README does not document a rollback path, and the gap between the latest tag (v0.24.1, 2024-05-06) and the current default branch means a build from master and a build from the latest release are not the same thing. Decide which one you are shipping before you wire Lux into anything automated.

The Go module declares go 1.24, so building from source requires a toolchain at least that new. That is a real constraint on older build images.

Editorial conclusion

Adopt Lux if you want one Go binary that turns a supported page URL into a file, and you are comfortable passing cookies or a proxy when a site pushes back. Do not adopt it if you need a graphical app, DRM-protected content, or a site that is not in the supported list and is not a plain direct file. Before relying on it, run lux -i against the exact URLs you care about and confirm that the streams and sizes it reports are the ones you expect.

Frequently asked questions

Official sources

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