Skip to content

Install FlexTool with the FlexTool GUI

This page describes how to install IRENA FlexTool using the built-in FlexTool GUI. This is the simplest installation path — it does not require Spine Toolbox (though you can optionally add it).

For the Spine Toolbox installation path, see Install with Spine Toolbox.

v4 is in alpha

FlexTool v4 is currently in alpha (4.0.0a1, released 2026-05-26). The release is published as a PEP 440 pre-release on PyPI, so pip needs the --pre flag to resolve it — e.g. pip install --pre flextool. Parity with the 3.47.x line is expected; reports against scenarios that worked on 3.47.0 but misbehave on 4.0.0a1 are especially welcome.

Requirements

  • Python ≥ 3.11 (see requires-python in pyproject.toml for up-to-date requirements)
  • Git (optional, but recommended for easy updates)

Installation Steps

1. Install Python

Download and install Python from python.org. Make sure to check "Add Python to PATH" during installation on Windows.

Note: If you already have Python in your PATH (check with python --version in a terminal) and it is older than 3.9, you need to install a supported version. On Windows, you may need to use the full path to the new Python (e.g. C:\Python312\python.exe) unless you update your PATH to point to it.

2. Install Git (optional)

Git makes it easy to update FlexTool in the future. The alternative is to download zip files manually.

  • Download and install from https://git-scm.com/downloads or use your system's package manager.
  • Windows tips: During git installation, the defaults are fine for most questions. Exceptions:
  • Text editor: switch from VIM to Nano (scroll upward) — unless you know and like VIM.
  • Use Windows' default console window (unless you know what you are doing).

3. Get FlexTool

Either clone with Git (recommended): 

git clone https://github.com/irena-flextool/flextool.git

Or download and unzip from GitHub.

4. Enter the FlexTool directory

All the remaining steps must be run from inside the FlexTool directory:

cd flextool

(Substitute the extracted folder name if you used the zip download.)

5. Create a Virtual Environment

Linux (Debian / Ubuntu / Mint): The system Python may not include venv with pip by default. Install it first:

sudo apt install python3-venv

Create a virtual environment inside the FlexTool directory:

python -m venv .venv

Activate the virtual environment:

Linux / macOS: 

source .venv/bin/activate

Windows: 

.venv\Scripts\activate

6. Install FlexTool

Recommended — install FlexTool with Spine Toolbox (includes Spine DB Editor for editing input databases):

pip install ".[toolbox]"

This installs FlexTool with the built-in GUI, HiGHS solver (via highspy), and Spine Toolbox with its dependencies (Spine DB Editor, Spine Items, Spine Engine, PySide6, etc.).

Lighter weight install (without Spine Toolbox)

If you prefer a leaner installation or have issues installing Spine Toolbox dependencies:

pip install .

This installs FlexTool and the GUI, but without Spine DB Editor. You can run scenarios and view results, but editing .sqlite input sources from the GUI requires Spine DB Editor. You can upgrade to the full install at any time by running the recommended command above.

Install from PyPI / TestPyPI (pre-release)

If you do not need a clone of the source tree, FlexTool can be installed directly from PyPI. Because v4 is an alpha, pip needs --pre to resolve it:

pip install --pre flextool                # lean / GUI only
pip install --pre "flextool[toolbox]"     # with Spine Toolbox

TestPyPI sometimes carries newer alphas than PyPI. To install from there, point pip at the TestPyPI index and keep PyPI as a fallback for dependencies that are not mirrored on TestPyPI:

pip install --pre \
    --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    flextool

The PyPI install does not include the update_flextool.py initialization script or the example databases that live alongside it. If you need those — or want the update_flextool.py migration workflow described below — install from a clone instead.

7. Initialize FlexTool

Create the necessary database files and templates:

python update_flextool.py --skip-git

8. Verify the install

Confirm the CLI is wired up:

flextool-run --help

This should print the FlexTool CLI usage. If it does, the venv is healthy.

9. Launch FlexTool

Start the FlexTool GUI:

flextool-gui

(Equivalent to python -m flextool.gui.)

If you also installed Spine Toolbox, you can launch it with:

spinetoolbox

Then open FlexTool project from the menu: File... Open project... Choose FlexTool folder.

Updating FlexTool

FlexTool update process will get the latest FlexTool version and then run a migration script that updates the databases to the latest version.

If you installed with Git:

cd flextool
source .venv/bin/activate   # Linux / macOS
.venv\Scripts\activate      # Windows
python update_flextool.py

If you installed from a zip file, download the latest zip, extract it over the existing directory, and run:

python update_flextool.py --skip-git

From the GUI

Click Update FlexTool… in the top-right of the main window (next to UI settings…). FlexTool detects how it is installed and runs the right upgrade automatically — git pull plus an editable reinstall for a git checkout, or pip install --upgrade for a PyPI install — and streams the output to the Execution window. Restart FlexTool when it finishes for the new version to take effect.

The dialog has an Install Spine Toolbox checkbox. Spine Toolbox is a large, optional dependency that is required to open .sqlite input sources in the Spine DB Editor; leave it unticked if you do not need it. (It is ticked by default when Spine Toolbox is already installed, so updating keeps it.)

Update notifications

By default FlexTool makes one lightweight check at startup — against PyPI, or your git remote for a git checkout — for a newer version. When one is available the Update FlexTool… button is highlighted. The check fails silently if you are offline or the network is restricted.

To disable it, untick Check for updates on startup in the Update FlexTool dialog (the choice is remembered), or set the environment variable FLEXTOOL_NO_UPDATE_CHECK=1 to suppress the check entirely.

Troubleshooting

"command not found: flextool-gui" / "flextool-run"

Make sure your virtual environment is activated. The flextool-gui and flextool-run console scripts are only on PATH when the venv where FlexTool was installed is active.

"No module named '_tkinter'" (macOS / Linux)

The FlexTool GUI uses tkinter, which is part of Python's standard library but depends on Tcl/Tk system libraries. Some platforms do not bundle these by default.

macOS (Homebrew Python): Install the Tcl/Tk binding for your Python version:

brew install python-tk@3.12

Replace 3.12 with your Python version (check with python3 --version).

Linux (Debian / Ubuntu): Install the system package:

sudo apt install python3-tk

Import errors or missing modules

Try reinstalling: 

pip install . --force-reinstall

Solver issues

FlexTool uses HiGHS by default — installed automatically via the highspy Python bindings, no additional setup needed.

It is also possible to wire in commercial solvers (e.g. CPLEX) for licensed users; see the documentation for details.