Installing flua on macOS — Python, pip, VS Code, and the usual bumps

flua needs Python, and Python on a Mac is where most of the confusion lives — several Pythons can exist side by side. This post walks through the install, the upgrade, where things land, and what to do when something does not work. No programming background required.

1. Install Python (with Homebrew)

flua needs Python 3.11 or newer. The cleanest way on macOS is Homebrew. First check whether brew is there:

brew --version          # prints "Homebrew ..." — if not, install from https://brew.sh

Then install Python and check it:

brew install python3    # installs the current Python
python3 --version       # should print Python 3.11 or newer
python3 -m pip --version

The python3 -m pip form matters: it always uses the pip that belongs to python3, even when several Pythons are installed.

2. Install flua

python3 -m pip install fibaro-flua

Test it — flua is now on your PATH:

flua --version

And a real smoke test. Save this as hello.lua:

function QuickApp:onInit()
  print("QuickApp initialized")
  exit(0)
end

and run it:

flua hello.lua

You should see QuickApp initialized in the log. No HC3 needed: without controller credentials flua runs against the emulated controller (force it anytime with flua --api local hello.lua).

3. Upgrade flua — and back down if needed

python3 -m pip install --upgrade fibaro-flua
flua --version          # confirm the new version

If a version turns out to have bugs, pin a known-good one instead of living with it:

python3 -m pip index versions fibaro-flua    # list every version on PyPI
python3 -m pip install fibaro-flua==0.1.17   # pin a known-good version

Same rules as the upgrade: run the command with the Python that owns your flua (head -1 $(which flua) — see troubleshooting below).

4. Where is it installed?

which flua               # e.g. /opt/homebrew/bin/flua (Apple Silicon)
                         # or  /usr/local/bin/flua (Intel)
which -a flua            # every flua on this machine (virtualenvs etc.)
head -1 $(which flua)    # which Python owns this flua

That last line shows the Python your flua runs on — the shebang of the installed command. Handy when upgrades do not seem to stick.

5. VS Code: the launch.json story

Run flua --tool setup in your QA project folder. It writes .vscode/launch.json and .vscode/tasks.json — the F5 run/debug configurations.

• The Run configurations launch flua through VS Code's selected Python interpreter — so open the command palette (Cmd+Shift+P) and run Python: Select Interpreter, choosing the Python you installed flua with. (If the menu is missing, install the Python extension.)
• The Debug configurations (mobdebug breakpoints) need flua's absolute path — --tool setup resolves it at setup time (which flua) and writes it into launch.json, so VS Code finds flua even though it does not inherit the shell's PATH. Re-run --tool setup after reinstalling flua somewhere else.

6. Troubleshooting

• flua: command not found — flua landed in a Python whose bin directory is not on your PATH. Install with the exact Python you use: which python3, then python3 -m pip install fibaro-flua. Until then python3 -m flua ... works everywhere flua would.
• VS Code cannot find flua when debugging — re-run flua --tool setup in the project (it re-resolves the absolute path). For the Run configurations, check the selected Python interpreter.
• externally-managed-environment error — newer Pythons refuse pip installs outside a virtual environment. Easiest fix: brew install pipx, then pipx install fibaro-flua (and pipx upgrade fibaro-flua for upgrades).
• pip tries to compile lupa and fails — your pip is too old to find the prebuilt wheel. python3 -m pip install --upgrade pip, then install flua again.
• Several Pythons, one flua — which -a python3 lists them all; head -1 $(which flua) shows which one owns flua. Upgrade with that interpreter: <that python> -m pip install --upgrade fibaro-flua.

Everything past step 2 — the emulator, the UI viewer, the VS Code debugger — is covered in the tutorial series here on the forum.

flua: https://github.com/jangabrielsson/flua · docs: USAGE.md · pip: https://pypi.org/project/fibaro-flua/