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

flua needs Python, and Python on Windows is where most of the confusion lives — several Pythons can exist side by side, and the one VS Code uses may not be the one your terminal uses. This post walks through the install, the upgrade, where things land, and what to do when something does not work. No programming background required.

All commands below are for PowerShell, not Command Prompt. On Windows 11, open Terminal from the Start menu and select a PowerShell tab. On Windows 10, Windows PowerShell works too. You do not need to run it as administrator.

1. Install Python

flua needs Python 3.11 or newer. The current Python installation route on Windows is the Python install manager, available from python.org or the Microsoft Store. Install the manager, then close and reopen PowerShell so the new commands are available.

Install a regular Python 3.13 runtime and check it. This guide uses 3.13 to keep the commands consistent — you do not need to replace a working flua installation that already uses a supported Python.

py install 3.13
py -3.13 --version
py -3.13 -m pip --version

Already installed Python with the traditional installer? Skip py install 3.13 if py -3.13 --version already works. The traditional installer has an Add python.exe to PATH checkbox; the new install manager has a different setup flow. The old Python launcher cannot run py install — if both are installed, pymanager install 3.13 explicitly calls the new manager. See the official Windows installation guide if the commands conflict.

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

2. Install flua

You do not need to download the repository or create a virtual environment to use flua. Install the published package with pip:

py -3.13 -m pip install fibaro-flua

If pip reports a permissions error for a shared Python installation, use py -3.13 -m pip install --user fibaro-flua or the optional virtual environment below, rather than running as administrator.

Test it:

flua --version

flua is not recognized? The install may have succeeded, but Python's executable directory for scripts is not on PATH. This form runs the package through the Python you installed it with, without needing to find flua.exe:

py -3.13 -m flua --version

Wherever this guide says flua ..., you can use py -3.13 -m flua ... instead. Step 5 explains the extra PATH step needed to let setup locate the debugger executable.

Create a folder for your QuickApps:

New-Item -ItemType Directory -Force "$HOME\flua-qas"
Set-Location "$HOME\flua-qas"

And a real smoke test. Save this as hello.lua in your QA folder, using VS Code or another text editor. Make sure the filename is not accidentally hello.lua.txt:

--%%mode:offline
function QuickApp:onInit()
  print("QuickApp initialized")
  exit(0)
end

Run it from the same folder:

flua --api local hello.lua

You should see QuickApp initialized in the log. No HC3 needed: --api local explicitly selects the emulated controller.

Optional: keep flua in a virtual environment

A virtual environment keeps this project's packages separate from other projects. This is useful for pip users too, not just people working from the repository. In your QA folder:

py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install fibaro-flua
.\.venv\Scripts\Activate.ps1
flua --version
flua --api local hello.lua

If PowerShell blocks the activation script, skip activation and keep using .\.venv\Scripts\flua.exe. You do not need to change your machine's security settings to run flua. deactivate leaves an activated environment.

Windows uses .venv\Scripts\flua.exe, not the macOS/Linux path .venv/bin/flua. For this route, use .\.venv\Scripts\python.exe in place of py -3.13 for the pip and Python commands below; the launcher command explicitly selects the base Python, not your project's environment.

3. Upgrade flua — and back down if needed

Use the same Python you installed flua with:

py -3.13 -m pip install --upgrade fibaro-flua
py -3.13 -m flua --version

If a version turns out to have bugs, list the available versions and install the one you want:

py -3.13 -m pip index versions fibaro-flua
py -3.13 -m pip install "fibaro-flua==VERSION"

Replace VERSION with a version number from the list. Do not switch to a bare pip for the upgrade — it might belong to another Python.

4. Where is it installed?

py -3.13 -c "import sys; print(sys.executable)"
py -3.13 -m pip show fibaro-flua
py -0p

The first command identifies the Python selected by the launcher. pip show shows the package version and location. py -0p lists the Python installations known to the launcher or install manager.

To see which flua a bare command would find:

Get-Command flua -All

If Python's scripts directory is not on PATH, that command may find nothing — py -3.13 -m flua still works. Unlike the macOS command, flua.exe is a launcher executable; there is no text shebang to inspect.

5. VS Code: the launch.json story

Install Visual Studio Code and use File → Open Folder to open your QA folder, not just hello.lua. From PowerShell in that folder, scaffold the project:

flua --tool setup

Setup writes .vscode/launch.json, .vscode/tasks.json, extension recommendations, Lua completion definitions, and agent files.

If flua is not on PATH: setup currently searches PATH to locate flua.exe. Merely running py -3.13 -m flua --tool setup does not fix that search; setup warns and falls back to the bare name. Find the installed launcher and temporarily add its directory first:

$fluaExe = py -3.13 -c "from importlib.metadata import distribution; d = distribution('fibaro-flua'); print(next(str(d.locate_file(f).resolve()) for f in d.files if f.name == 'flua.exe')))"
$env:Path = "$(Split-Path -Parent $fluaExe);$env:Path"
py -3.13 -m flua --tool setup

This reads the installed package's file list, so it also finds launchers from a pip --user installation. The PATH change applies to this PowerShell session only; it is not a permanent system change. For the optional virtual environment route, instead use:

$env:Path = "$(Resolve-Path .\.venv\Scripts);$env:Path"
.\.venv\Scripts\flua.exe --tool setup

Moving the project or recreating the environment? The generated debugger and task paths may need updating. Setup keeps existing files; plain --tool setup does not refresh them. --tool setup --force regenerates setup's files, but also overwrites other scaffolded files and directories. Back up customizations first, or edit just the interpreter and task paths. A macOS .venv cannot be copied to Windows — create a new environment on each machine.

6. Troubleshooting

7. What is different on Windows 10?

The PowerShell commands and environment paths above are the same on 64-bit Windows 10. Python 3.13 can run on Windows 10. You may use Windows PowerShell instead of the newer Terminal app; flua itself needs neither WSL nor a Unix shell.

The important difference is the operating system's support status. Windows 10 Home and Pro reached ordinary end of support on October 14, 2025. Extended Security Updates and LTSC editions have separate arrangements; check which applies to your machine. VS Code's current requirements refer to supported Windows client versions, so do not assume future Python, VS Code, extensions, or wheels will keep supporting an out-of-support Windows 10 installation. Windows 11 is the recommended platform for a new setup.

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

flua: GitHub · user guide · PyPI
Windows references: Python install manager · Python 3.13 on Windows · VS Code requirements · Windows 10 lifecycle