Skip to content

Install FlexTool with Spine Toolbox

This page describes the Spine Toolbox installation path for IRENA FlexTool. Spine Toolbox is the heavier, multi-tool integration path: it wraps FlexTool as one node in a directed-acyclic-graph (DAG) workflow alongside other tools and data stores.

Most users do not need this path. If your work is centred on FlexTool itself — building scenarios, running them, inspecting results — follow Install with FlexTool GUI instead. The Spine Toolbox path is intended for users who already use Spine Toolbox or who combine FlexTool with other Spine-based models. See Choosing an interface for the side-by-side comparison.

Requirements

  • Python ≥ 3.11 (see requires-python in pyproject.toml for up-to-date requirement)
  • 64-bit Windows 10 or 11, Linux or macOS. Windows 7 and 8.1 cannot run FlexTool 4 (its libraries need Windows 10). If a library reports "DLL load failed" on Windows, install the Microsoft Visual C++ Redistributable (x64, https://aka.ms/vs/17/release/vc_redist.x64.exe).
  • Processor (Intel/AMD): at least SSE4.2 and POPCNT (x86-64-v2: Intel Core i3/i5/i7 from 2009 on, AMD FX or Ryzen; Core 2 and Phenom II are not supported). AVX2 (most processors from 2013 on) runs the fastest build. Without AVX2 (for example Celeron/Pentium laptops up to about 2021, Intel Core before 2013, AMD FX), FlexTool uses the compatible build of the polars data library (about 10-30% slower): add the compat extra (pip install "flextool[compat]"). Without it, FlexTool says why it needs the compatible build and gives the pip command: in a terminal it asks before running it, the GUI asks at startup (in its terminal, or in a small yes/no dialog when started from a shortcut) before it loads polars and closes if you decline, a Spine Toolbox tool stops with the message, and flextool-update installs it. Run python -m flextool.env_check to see what FlexTool found.
  • 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.11, 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 with Spine Toolbox

Install FlexTool and the toolbox extra. This pulls in Spine Toolbox alongside FlexTool's core dependencies (declared in pyproject.toml):

pip install ".[toolbox]"

The extra brings in Spine Toolbox itself, Spine DB Editor, Spine Items, Spine Engine, PySide6, and the rest of Spine Toolbox's runtime stack. On a slow link you may want --timeout=10000.

If you would rather install from PyPI than work from a clone, the same extra works there:

pip install "flextool[toolbox]"

7. Initialize FlexTool

Create the necessary database files and templates (skip the --skip-git flag if you cloned with git and want update_flextool.py to fetch upstream changes too):

python update_flextool.py --skip-git

8. Verify the install

Confirm the FlexTool CLI is wired up:

flextool-run --help

This should print the FlexTool CLI usage. FlexTool runs independently of Spine Toolbox, so this check passes even before Toolbox is launched — useful for isolating environment issues from Toolbox UI issues.

9. Launch Spine Toolbox

spinetoolbox

Then open the FlexTool project from the menu: File... Open project... and choose the FlexTool directory (not a file inside it).

Updating FlexTool

The update flow mirrors Install with FlexTool GUI: pull the latest FlexTool, then migrate the input databases.

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

update_flextool.py brings the databases to the current schema version without destroying data (a backup is still good practice):

  • it migrates the database selected as Input data in the project, input_data.sqlite and templates/input_data_template.sqlite;
  • it rebuilds the example databases (templates/examples.sqlite, templates/time_settings_only.sqlite and the databases in how to example databases/) from the current templates.

To migrate any other database separately:

python migrate_database.py path/to/database.sqlite

Spine Toolbox itself updates separately. With the FlexTool venv active:

pip install --upgrade spinetoolbox

Update troubleshooting

  • If git reports merge conflicts, it is almost always because the template files were modified locally. Restore the tree with git restore . and re-run git pull, then python update_flextool.py.
  • results.sqlite only ever receives additive changes (to protect data), which leaves old parameter definitions lingering. To clear them, replace the database with a copy of the up-to-date templates/results_template.sqlite.

Troubleshooting

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

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

Linux / macOS notes

FlexTool calls HiGHS through the highspy Python bindings, which install automatically as a dependency, so no separate solver binary is needed. Prebuilt highspy wheels cover x86-64 Linux, Windows and macOS, and ARM64 Linux and macOS (Apple Silicon). On other platforms you need to build HiGHS / highspy from source.

Spine Toolbox runs on Linux and macOS as well, with occasional minor graphical glitches on macOS.

Import errors or missing modules

Try reinstalling:

pip install ".[toolbox]" --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.