Plugins / FLIMKit / Requirements and Installation · edit on GitHub

Requirements & Installation

System Requirements

• Python ≥ 3.12 (3.14 recommended, official builds use 3.14)
• macOS, Linux, or Windows

Dependencies

Installation

No Python, no terminal

Download the build for your machine from the Releases tab, unzip it, and run it. Python is inside it, so there is nothing else to install. FLIMKit-windows.zip, FLIMKit-macos.zip and FLIMKit-linux.zip are attached to every release, built by GitHub Actions on each tag. Each release also carries this documentation as a PDF, FLIMKit-docs-<version>.pdf, so the docs for the version you are running stay available after the wiki moves on.

Code merged into dev after a release is built too, as FLIMKitDEV (Development builds).

On macOS the app is self-signed, so the first launch needs right-click then Open. A double-click will be refused.

This route gets the desktop application only. It carries no GPU backend unless the build machine had one, which is covered under GPU acceleration in the compiled app.

Setting up a Python environment

Install FLIMKit into its own environment, not the system Python, so its packages don't collide with anything else. conda and uv both work. Pick one and use it for everything FLIMKit, plugins included: a package installed into a different environment is never seen.

With conda (Miniforge, Miniconda or Anaconda):

conda create -n flimkit -c conda-forge python=3.14
conda activate flimkit
pip install "flimkit[gui]"

With uv:

uv venv --seed --python 3.14 flimkit-env
source flimkit-env/bin/activate      # Windows: flimkit-env\Scripts\activate
uv pip install "flimkit[gui]"

--seed puts pip into the environment. uv leaves it out by default, and install.py calls pip, so without it python install.py fails. Once the environment is active, every pip install below also works as uv pip install.

FLIMKit and all of its dependencies come from PyPI as wheels, so neither tool gets you a different or better install. The differences are around it:

• uv is a single binary, installs a lot faster than pip, and downloads Python 3.14 itself if you don't have it.
• A uv environment is a folder where you created it, and you activate it by path. A conda environment has a name and can be activated from anywhere.
• If you already use conda, or a shared machine or cluster provides it, stay with conda. There is nothing to gain from adding a second tool.

From PyPI

For analysis in scripts, notebooks and the terminal:

pip install flimkit                 # readers, fitting, phasors, stitching, the CLI
pip install "flimkit[gui]"          # adds the desktop window

This is the right route for a server, a container, or anywhere you only want the library. It installs no Tkinter packages, so it works on a machine with no display and no python3-tk.

Extras combine, so ask for whichever apply:

Counts are from a resolve on macOS and will differ a little by platform, mostly in how much PyTorch brings with it.

A pip install fits on the CPU. GPU acceleration needs a backend, and what pip can give you depends on the platform:

Windows and ROCm need a wheel from PyTorch's own index rather than PyPI, which package metadata cannot ask for. That is what install.py is for:

git clone https://github.com/FLIMKit/FLIMKit.git
cd FLIMKit
python install.py

install.py installs the requirements, then detects the hardware and installs the matching GPU backend (MLX on Apple Silicon, CUDA on NVIDIA, ROCm on AMD, CPU-only otherwise). No flags needed for a standard install. Clone it too if you want the terminal CLIs at the repository root, fit_cli.py, phasor_cli.py and synth_cli.py, which are not part of the package.

python install.py --dev      # also installs PyInstaller and test requirements
python install.py --dry-run  # preview commands without executing

Updating a clone

python update.py             # pull the latest code, then rerun install.py
python update.py --dry-run   # show what would happen without changing anything
python update.py --dev       # pass --dev on to install.py
python update.py --force     # rerun install.py even with nothing to pull

If dist/ holds an app you built with build_and_sign.py, update.py rebuilds it after pulling. --app-path then copies the new build over the copy you open, and --no-rebuild skips it. Rebuilding needs PyInstaller, from python install.py --dev, and stops if that app is running.

python update.py --app-path /Applications/FLIMKit.app
python update.py --rebuild   # rebuild even when there was nothing to pull

--release and --dev-release leave the clone alone and replace the app at --app-path with the latest build from GitHub, the same download as the button in the app (Updating the app).

Run it with the Python from your FLIMKit environment, so the requirements go into the right place. It only fast-forwards: with uncommitted changes to tracked files, or with local commits that the remote doesn't have, it stops and changes nothing. If a separate installed copy of flimkit sits in that environment, which would be imported in place of the clone, it is reinstalled from the clone. It needs git on the PATH, and works the same on macOS, Linux and Windows.

Validate Installation

python validate_installation.py

Runs 10 checks: dependencies, module imports, XLIF parsing, stitching, fitting, phasor pipeline, per-tile fit pipeline, and GPU backend dispatch. All should pass.

Hardware Limits

python hardware_limits.py

Stress-tests the machine by ramping canvas sizes (64×64 → 4096×4096) and measuring fixed-tau GPU and free-tau CPU throughput. Reports peak pixels/second, RAM headroom, and estimated wall-clock times for common acquisition sizes. Useful for understanding what canvas sizes are feasible before starting a long batch run.