← All Notes

Install LedFx on Ubuntu 24.04

ledfx, ubuntu, command-line

Short reference for installing LedFx on Ubuntu 24.04 LTS using an isolated Python environment, plus the audio issues I ran into.

Why use a virtual environment?

Ubuntu’s system Python is managed by the OS, so installing packages directly into it with pip can conflict with Ubuntu-managed Python packages.

A virtual environment keeps LedFx and all its Python dependencies inside one directory:

~/.local/share/ledfx/

I used the explicit version of a virtual-environment install. Instead of activating it with:

source ~/.local/share/ledfx/bin/activate

and then running python, pip and ledfx, I called the executables inside it directly.

Both approaches produce essentially the same installation. The explicit version just makes it obvious which Python/environment is being used and does not alter the current shell.

Check Python

Ubuntu uses python3, so python not existing is not a problem.

python3 --version

LedFx currently requires Python 3.10–3.13.

Install

Creating the environment:

python3 -m venv ~/.local/share/ledfx

Installing LedFx into it:

~/.local/share/ledfx/bin/python -m pip install ledfx

Running it:

~/.local/share/ledfx/bin/ledfx

Then open:

http://localhost:8888

There is no need to recreate or reinstall the environment after reboot.

Make ledfx available as a command

Adding the following to ~/.bashrc:

# LedFx
alias ledfx="$HOME/.local/share/ledfx/bin/ledfx"

Reload Bash once:

source ~/.bashrc

After that:

ledfx

is enough to start it.

PortAudio error

LedFx initially failed with:

OSError: PortAudio library not found

Install the missing Ubuntu runtime library:

sudo apt install libportaudio2

Then start LedFx again.

Audio-reactive effects not reacting

WLED was discovered and normal effects worked, but music-reactive effects received no system audio.

On this Ubuntu setup, LedFx showed these audio devices:

hd-generic
pipewire
default

rather than the pulse device mentioned in LedFx’s older Linux audio instructions.

Use:

pipewire

If effects still receive no audio, install the audio-routing control:

sudo apt install pavucontrol

Run:

pavucontrol

While music is playing and LedFx has an audio-reactive effect active:

  1. Open Recording.
  2. Find the LedFx/Python/ALSA plug-in recording stream.
  3. Set its capture source to Monitor of the audio output currently playing the music.

LedFx’s Linux documentation uses the same monitor-routing approach, although its instructions were tested with the older PulseAudio setup on Ubuntu 20.10.

Should I install LedFx differently next time?

Probably not.

The explicit virtual-environment approach is useful on Ubuntu because:

  • it does not touch Ubuntu’s system Python packages;
  • everything Python-related to LedFx stays under ~/.local/share/ledfx;
  • it requires no activation step;
  • the exact Python and LedFx executables being used are obvious;
  • removing the environment removes the Python installation cleanly.

The more conventional activated-venv version is also completely fine:

python3 -m venv ~/.local/share/ledfx
source ~/.local/share/ledfx/bin/activate
python -m pip install ledfx
ledfx

It is not inherently better. Activation is just a convenience that temporarily puts the environment’s bin/ directory first in the shell’s PATH.

I prefer the explicit version here because LedFx is an application I want to install once and run, rather than a Python project whose environment I need to work inside regularly.