xLights on Linux: Build It From Source, Then Sequence Your First Show

What xLights Is For, and Who Ends Up Using It

xLights is a sequencer for lights. The repository describes it as an object oriented program in which you create sequences, build playlists, schedule them, test your hardware and convert between different sequencers. It ships USB and E1.31 drivers, which places it in the part of the hobby where a computer is the source of the show rather than a single embedded controller.

The people this fits are the ones running a display with many outputs: pixel matrices, props on multiple universes, a mix of DMX and pixel controllers. Those users need a timeline editor, a way to map effects onto physical outputs, and something that can replay the result unattended on a schedule. A user with one strip and a phone app is not the target, and the install path reflects that: the README treats Linux as a developer build problem, not a consumer download.

The project is not archived. The last push to the master branch was on 2026-08-29, and the most recent tagged release in the list is 2026.16 from 2026-08-24, with a nightly build carrying the same timestamp as the last push. That cadence matters if you depend on a fix landing before show season.

Licensing is GPL-3.0, and the repository carries a License.txt at the top level. If you plan to redistribute a modified build or bundle it into a product, read that file rather than assuming the desktop application and your own sequence files are governed the same way. Sequences you author are your own work; the program itself is not.

How xLights Is Put Together: wxWidgets, Vendored Submodules and Optional GPU Backends

The architecture visible in the repository is a C++ application built on wxWidgets as the cross-platform compatibility layer, with a minimum wxWidgets version of 3.1.5. The provided makefile will download and build wxWidgets if needed, including a patch the README mentions at the end of the file to fix the sizing of bitmap buttons. That single detail tells you something about the project's age and its dependency posture: it pins a wxWidgets tag, `xlights_2026.17c`, rather than tracking upstream.

The tree is split into src-core, src-ui-wx, src-iPad, xLights and xlDo, with separate README files per platform (README.linux, README.osx, README.windows). SDL2 must be 2.0.5 or later. A precompiled libliquidfun.a library and QM Vamp plugins are included for i686, x86_64 and aarch64, and the README says other platforms would need to recompile them from the google/liquidfun repository. Audio analysis, in other words, ships as a binary blob per architecture rather than as source in the tree.

The interesting part is what is optional. GPU-accelerated rendering under Vulkan compiles compute kernels from src-core/effects/vulkan/shaders/*.comp to SPIR-V at build time using glslc, and the Vulkan headers, the volk loader and VulkanMemoryAllocator are vendored as git submodules fetched by the recursive submodule checkout. Nothing Vulkan is linked; volk loads the driver at runtime. The Vulkan Shader effect additionally translates user GLSL at runtime through glslang, which the README notes comes from the distro and pulls in spirv-tools because the packaged glslang is built with the SPIR-V optimizer enabled. If you do not want any of this, the README gives you an escape: build with -DXLIGHTS_USE_VULKAN=OFF or omit it in the .cbp to skip the GPU compute backend entirely.

Installing xLights on Linux: Packages, Build and the mDNS Trap

For users who do not want to compile, the README points to Ubuntu packages at https://code.launchpad.net/~chris-debenham/+archive/ubuntu/xlights. The source build below is the developer path.

Ubuntu 24.04 is the minimum supported release and is what the official builds and CI are compiled on. Fedora 42 is also listed as tested; other distributions will vary. Start with the dependency set. The README gives this apt command, and the list is long because the application pulls in GTK, GStreamer, FFmpeg, SDL2, Lua, WebP and font libraries:

sudo apt-get install g++ gcc build-essential libgtk-3-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev freeglut3-dev libavcodec-dev libavformat-dev libswscale-dev libsdl2-dev libavutil-dev libavfilter-dev libzstd-dev libwebp-dev libcurl4-openssl-dev liblua5.3-dev libminizip-dev libxlsxwriter-dev libegl-dev libfreetype-dev libharfbuzz-dev libfontconfig-dev libavahi-compat-libdnssd-dev wget git cbp2make curl libsecret-1-dev

One package in that list deserves attention. libavahi-compat-libdnssd-dev supplies <dns_sd.h>. Without it, the README states that mDNS-based controller discovery silently compiles out and WLED controllers will not be auto-discovered, with no build error. At runtime you also need the daemon:

sudo apt-get install avahi-daemon
sudo systemctl enable --now avahi-daemon

If you want GPU rendering, glslc is a required build tool, like ispc for the SIMD kernels, and the distro supplies glslang:

sudo apt-get install glslc glslang-dev

At runtime the machine needs a Vulkan loader and an ICD. Without them xLights logs "no Vulkan loader" and falls back to CPU rendering, per the README:

sudo apt-get install libvulkan1 mesa-vulkan-drivers

The README notes mesa-vulkan-drivers covers Intel and AMD, while NVIDIA users get Vulkan from the proprietary driver, and that the setting lives under Preferences > Other > GPU rendering. A container route exists if you would rather not touch your local install:

docker build -t xlights-build https://github.com/xLightsSequencer/xlights-build-docker.git
docker run --name buildvm xlights-build /bin/bash Recipe

The same README shows `Recipe.appimage` in place of `Recipe` to produce an AppImage, and `docker rm buildvm` to discard the container before a fresh build. Fedora users have extra work: cbp2make is not in an official repo, so the README has you clone mirai-computing/cbp2make, run `make -f cbp2make.cbp.mak.unix`, and install the binary to /usr/local/bin. Fedora also defaults to ffmpeg-free, and the README's remedy is to add the rpmfusion repo and swap: `sudo dnf swap ffmpeg-free ffmpeg --allowerasing`.

For a first real use, the sequence is: launch xLights, create a new sequence, add a controller under the controller setup, and use the hardware test function to push a few seconds of colour to your outputs before you spend an evening on a timeline. The repository description lists testing your hardware as one of the program's jobs, and that is the cheapest way to confirm your E1.31 universes or USB dongle are wired the way you think.

Where the Build and the Runtime Will Bite You

The silent mDNS failure is the sharpest limitation in the README, because the symptom appears at runtime, not at build time. You compile successfully, open the program, and WLED controllers never appear. Nothing told you that a header was missing. If discovery is part of your workflow, treat libavahi-compat-libdnssd-dev as mandatory rather than optional and confirm avahi-daemon is enabled.

The Vulkan path has a similar shape. Missing glslc stops the build; missing libvulkan1 or a driver does not, it just drops you to CPU rendering with a log line. That is a reasonable design for portability, but it means a machine that looks configured can be running the slow path. The README's own check for the video side is `vainfo`, which prints VAProfile lines when the driver initializes. Hardware video decode has no build-time dependency because it goes through FFmpeg's generic hwaccel API, but the runtime driver is on you: intel-media-va-driver or intel-media-va-driver-non-free for Intel, mesa-va-drivers for AMD and Mesa. The setting is under Preferences > Other > Hardware Video Decoding, and the README says it auto-tries vaapi then vdpau with no manual selection.

The platform floor is a real constraint too. Ubuntu 24.04 is the only baseline continuously verified, per the README, and older releases may happen to work but are not tested and not supported. If your show machine is an older LTS box you keep offline for stability, you are outside the supported set. The same applies to architectures outside i686, x86_64 and aarch64, where the bundled libliquidfun and QM Vamp plugins do not apply and you would have to recompile them yourself.

Finally, this is a desktop sequencer, not a headless render farm. The repository layout shows an iPad target under src-iPad and a plan document, but the README in front of us documents Linux, macOS and Windows builds. If you want a server that renders FSEQ files on a schedule with no GUI, the README does not describe that path.

xLights Against WLED Alone

The most common alternative for someone reading this is not another desktop sequencer. It is running the show on the controller itself. WLED runs on an ESP32, serves its own web interface, and handles effects, presets and simple playlists without a PC in the loop. The difference in approach is where the timeline lives.

With WLED alone, the effect is generated on the microcontroller and the show is limited by that device's memory and CPU. xLights inverts this: the desktop application does the sequencing and rendering, and the controller receives pixel data over E1.31 or a USB dongle. That is why the README bothers with mDNS discovery for WLED controllers at all. The two are not mutually exclusive, and the phrase people search for, using xLights with WLED, describes the hybrid: xLights as the sequencer, WLED as the receiver.

The trade-off is honest. A PC-driven show gives you a timeline editor, playlists, scheduling and conversion between sequencers, which is the whole point of the program. It also gives you a machine that must be running, a network that must be reliable, and a build that depends on GTK, FFmpeg and a Vulkan stack. For a single prop with a dozen effects, WLED alone is less to maintain. For a display where you need to line up audio, video and hundreds of pixel outputs, the desktop sequencer is doing work the ESP32 cannot.

Maintenance, Releases and What the Licence Implies

xLights ships on a rapid cadence. The release list shows 2026.15 on 2026-08-04, 2026.16 on 2026-08-24, and a nightly at the same timestamp as the last master push on 2026-08-29. The makefile pins a wxWidgets tag named xlights_2026.17c, which suggests the next release line is already in preparation. For a show operator this is a mixed blessing: fixes arrive quickly, but so does churn, and the version number itself is date-like, so a new build every few weeks is normal rather than exceptional.

The upgrade cost is dominated by the toolchain, not the application. Because the makefile can download and build wxWidgets and applies its own patch, a rebuild can pull a new wxWidgets tag and recompile a large library before it touches xLights itself. The recursive submodule checkout for the Vulkan headers, volk and VulkanMemoryAllocator adds another moving part. If you build in the Docker image, that cost is contained; if you build locally, budget time for it.

On licensing, GPL-3.0 with a License.txt at the top level. The practical implication is that distributing a modified xLights build carries source obligations, and bundling it into a closed product is not the same as using it to run your own display. The README does not discuss commercial redistribution, so if that is your plan, read License.txt and the CONTRIBUTING.md in the tree rather than inferring terms from the README.

Editorial conclusion

Adopt xLights if you run a pixel or DMX display and want sequencing, playlists, scheduling and hardware test in one GPL-3.0 desktop application, and you are willing to build it on Ubuntu 24.04 or install the Ubuntu packages from the Launchpad PPA. Do not adopt it if your show is driven by a single small ESP32 controller with a handful of effects, because the sequencer, the wxWidgets toolchain and the GPU stack are more machinery than that job needs. Before committing, verify that your controller answers on the network or USB port you plan to use, that libavahi-compat-libdnssd-dev was present at build time if you expect mDNS discovery, and that `vainfo` reports a working VA-API driver if you intend to decode video on the GPU.

Frequently asked questions

Official sources

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