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. We will use an even more explicit path after creating the project environment.

2. Install flua in a project environment

A virtual environment keeps this project's Python packages separate from other projects. Create a QA folder under your home directory, then install flua into its .venv folder:

New-Item -ItemType Directory -Force "$HOME\flua-qas"
Set-Location "$HOME\flua-qas"
py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install fibaro-flua

Test it:

.\.venv\Scripts\flua.exe --version

Windows uses .venv\Scripts\flua.exe, not .venv/bin/flua. The latter is the macOS/Linux path. Using the full relative path also avoids PATH problems and does not require activating the environment.

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:

.\.venv\Scripts\flua.exe --api local hello.lua

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

Optional: shorter commands. Activate the environment in each new PowerShell session:

.\.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.

3. Upgrade flua — and back down if needed

From the QA folder, use the Python inside that project's environment:

.\.venv\Scripts\python.exe -m pip install --upgrade fibaro-flua
.\.venv\Scripts\flua.exe --version

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

.\.venv\Scripts\python.exe -m pip index versions fibaro-flua
.\.venv\Scripts\python.exe -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?

.\.venv\Scripts\python.exe -c "import sys; print(sys.executable)"
.\.venv\Scripts\python.exe -m pip show fibaro-flua
Get-Item .\.venv\Scripts\flua.exe
py -0p

The first command identifies the Python running this project. 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 the environment is not activated or on PATH, that command may find nothing — the explicit .\.venv\Scripts\flua.exe 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:

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

The first line puts this environment's executable directory on PATH for this PowerShell session only. It lets setup discover the absolute path to flua.exe, even if you did not activate the environment. Setup writes .vscode/launch.json, .vscode/tasks.json, extension recommendations, Lua completion definitions, and agent files.

• Install the recommended Python, Lua MobDebug (alexeymelnichuk.lua-mobdebug), and Lua Language Server extensions when VS Code offers them.
• The Run configurations launch flua through VS Code's selected Python interpreter. Open the command palette with Ctrl+Shift+P, run Python: Select Interpreter, and choose your project's .venv\Scripts\python.exe. If it is not listed, use Enter interpreter path.
• The Debug configurations use mobdebug for Lua breakpoints, stepping, and variable inspection. Setup writes the absolute path to flua.exe into these configurations. Open your Lua file, choose Flua: Debug Current File (mobdebug) in Run and Debug, and press F5.
• The UI configurations also start the viewer. Open the URL flua prints, normally http://127.0.0.1:8090/. A busy port makes flua try the next one. The UI server stays up until you stop the run.

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

• py is not recognized — reopen PowerShell after installing Python. If you only have a traditional Python installation without the launcher, check python --version and use python -m venv .venv instead, provided it is Python 3.11 or newer.
• python opens the Microsoft Store — this can be a Windows app execution alias rather than your installed Python. Use the working py -3.13 command, or inspect Manage app execution aliases from Start. Do not disable the install manager's aliases indiscriminately — they may be the commands you need.
• flua is not recognized — use .\.venv\Scripts\flua.exe, or activate the environment. .\.venv\Scripts\python.exe -m flua ... also works.
• Activate.ps1 cannot be loaded because running scripts is disabled — activation is optional. Use the explicit executable paths above. On a managed work computer, follow your administrator's policy rather than changing execution policy.
• VS Code cannot find flua when debugging — check the interpreter path in the chosen mobdebug configuration. For Run configurations, check Python: Select Interpreter. If you edit JSON paths by hand, escape backslashes: "C:\\Users\\YourName\\flua-qas\\.venv\\Scripts\\flua.exe".
• pip tries to compile lupa and fails — first upgrade pip using the environment's Python. Prefer regular 64-bit Python on an Intel/AMD PC; wheels depend on Python version and CPU architecture. If no wheel is available for your combination, try a supported Python with a matching wheel rather than immediately installing a compiler. flua does not need a separate Lua installation.
• The startup rocket is escaped or causes UnicodeEncodeError — flua's CLI has a UTF-8 output fix; upgrade to a release containing it when available. Until then, set $env:PYTHONIOENCODING = "utf-8" before running it from PowerShell. For F5 launches, fully close VS Code and launch it from that PowerShell session with code ., so it inherits the setting (the code command must be on PATH). A square in place of the rocket can also mean your font lacks that glyph.
• Several Pythons, one flua — use py -0p and Get-Command flua -All to see what is installed and on PATH. Using .\.venv\Scripts\python.exe -m pip ensures upgrades go into this project, not somewhere else.

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