Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GMLC-TDC/HELICS/llms.txt

Use this file to discover all available pages before exploring further.

HELICS can be installed in several ways depending on which language you plan to use and whether you need the core C/C++ library, a specific language binding, or the full HELICS toolchain. The most common path for Python users is a single pip install command. C and C++ users can download pre-compiled binaries from GitHub releases or build from source. This page covers all supported installation methods across platforms.
You need an internet connection to download HELICS. As of HELICS v3, the only supported language bindings included with the core C/C++ library downloads are C and C++98 (plus C++17 when building from source). Language bindings for Python, Julia, Java, and MATLAB are installed separately through their own package managers or build steps.
For most users, installing the Python binding is the fastest way to get started and gives you access to helics_broker and the HELICS CLI runner tool: 
pip install 'helics[cli]'
The [cli] extra installs the optional but recommended helics_cli runner, which is used in the HELICS user guide examples to launch federations from a single command. If you only need the Python API without the runner: 
pip install helics
Both commands work on supported versions of Windows, macOS, and Linux. See the HELICS PyPI page for the full list of supported platforms.

​
Platform-specific installation

pip install 'helics[cli]'

​
Install via Spack (HPC environments)

Spack is the recommended install method for high-performance computing clusters where you need fine-grained control over dependencies:
spack install helics
To enable MPI support:
spack install helics +mpi
To see all available build options:
spack info helics

​
Build from source (Ubuntu 22.04+)

Building from source requires:
  • GCC 11 or clang 15 (C++20 support)
  • CMake 3.22 or newer
  • Boost 1.73 or newer
  • ZeroMQ 4.2 or newer
Install dependencies:
sudo apt install libboost-dev libzmq5-dev git cmake-curses-gui
Clone and build:
git clone https://github.com/GMLC-TDC/HELICS
cd HELICS
mkdir build && cd build
cmake ../
make
make install
Verify the installation:
helics_broker --version

​
Package manager install commands

pip install 'helics[cli]'

​
Pre-compiled binaries

Pre-compiled binaries for Linux, macOS, and Windows are available from the HELICS GitHub releases page. Each release provides:
  • Zip archives with static libraries for multiple Visual Studio versions on Windows
  • A Windows installer with HELICS apps and the shared library
  • A C shared library archive with headers for third-party language interface builders
Download the appropriate archive for your platform, extract it, and add the bin folder to your system PATH.

​
Docker

A Docker image is available on Docker Hub with the core HELICS executables (helics_broker, helics_app, helics_recorder, helics_player, and helics_broker_server). This image does not include language binding libraries — it provides the apps only. 
docker pull helics/helics
docker run --rm helics/helics helics_broker --version
You can also build a custom Docker image with Python support using the following Dockerfile: 
FROM ubuntu:22.04 as builder

WORKDIR /root/develop

RUN apt update && apt install -y \
  libzmq5-dev python3-dev \
  libboost-all-dev \
  build-essential swig cmake git

RUN git clone --recurse-submodules \
  https://github.com/GMLC-TDC/HELICS.git helics

WORKDIR /root/develop/helics

RUN cmake \
  -DCMAKE_INSTALL_PREFIX=/helics \
  -DCMAKE_BUILD_TYPE=Release \
  -B build

RUN cmake --build build -j -t install


FROM ubuntu:22.04

COPY --from=builder /helics /usr/local/

ENV PYTHONPATH /usr/local/python

RUN apt update && apt install -y --no-install-recommends \
  libboost-filesystem1.74.0 libboost-program-options1.74.0 \
  libboost-test1.74.0 libzmq5 pip python3-dev

RUN pip install helics

CMD ["python3", "-c", "import helics; print(helics.helicsGetVersion())"]
Build and run: 
docker build -t helics .
docker run -it --rm helics

​
Language bindings

HELICS provides official language bindings beyond the core C and C++ library. Each binding is maintained in its own repository and installed through the language’s native package manager.

​
Python (pyhelics)

pip install helics
The Python binding is the most commonly used interface and is maintained in the pyhelics repository. It includes the full HELICS API plus the optional CLI runner when installed with pip install 'helics[cli]'.

​
Julia

pkg> add HELICS
The Julia binding is available in the HELICS.jl repository.

​
MATLAB and Octave

The MATLAB and Octave interfaces are available in the matHELICS repository. Follow the installation instructions in the matHELICS README.
The Octave interface requires Octave 8.3 or newer for mex file support.

​
Java (jHELICS)

Java support is built from source with the CMake option HELICS_BUILD_JAVA_INTERFACE=ON: 
cmake -DHELICS_BUILD_JAVA_INTERFACE=ON ../
make && make install

​
C#

C# support requires SWIG and is built from source with HELICS_BUILD_CSHARP_INTERFACE=ON. Install SWIG first: 
pip install swig
Then build HELICS: 
cmake -DHELICS_BUILD_CSHARP_INTERFACE=ON ../
make && make install

​
Verification

After installation, verify that HELICS is working by checking the broker version: 
helics_broker --version
You should see output like: 
3.x.x (20XX-XX-XX)
For Python, verify the binding: 
import helics
print(helics.helicsGetVersion())

​
Running an example

Once installed, the Quickstart walks through running a two-federate battery and charger co-simulation as a practical test of your installation.

Build docs developers (and LLMs) love

Get started for freeTalk to us