Installation Instructions

This page explains how to install Secondo and the tools it requires on your computer. The currently supported and CI-verified paths are a build from sources on Ubuntu / Debian, precompiled .deb binary packages for Ubuntu, a Container image for Docker and other container platforms, and a build on macOS using Homebrew. Older distributions are covered by the historical installation guides. The build of Secondo from sources itself is explained on the Sources page.

Which installation is right for you?

Just want to try Secondo in a few seconds → use a container image
Just want to install Secondo on Ubuntu → binary .deb packages (apt-get)
Build or extend Secondo on Ubuntu / Debian → installation from sources
Build or extend Secondo on macOS → installation with Homebrew
Older distributions (Fedora, SuSE, older Ubuntu) → historical installation guides

Using SECONDO in a Container

The fastest way to try Secondo is to run the official container image. It bundles Secondo and all of its dependencies, so no local installation is required — only Docker (or another OCI-compatible container runtime).

Start the container. A named volume (secondo-databases) keeps your databases on the host, so they survive container restarts and upgrades:

docker run -d --name secondo -p 8000:8000 -p 1234:1234 \
    -v secondo-databases:/var/lib/secondo/databases \
    ghcr.io/secondo-database/secondo:latest

Afterward, you can access the Secondo GUI in your browser at http://localhost:8000.

To instead work with the client-server console SecondoTTYCS inside the running container:

docker exec -it secondo SecondoTTYCS

Stop the container when you are done, and start it again later with docker start secondo:

docker stop secondo

Binary Installation via `.deb` Packages

For users who just want to try Secondo without compiling it, we provide precompiled .deb packages for Ubuntu 22.04, 24.04 and 26.04. They install Secondo and all of its dependencies within a few minutes via apt-get, and are the recommended starting point for new users. Developers who want to build their own extensions should instead build from sources as described below.

See the Ubuntu installation guide using apt-get for the full instructions. Note that these packages are built for the x86_64/amd64 architecture only; on other architectures (e.g. arm64) please build from sources.

Installation on Ubuntu / Debian

The steps below install the tools required to compile Secondo and then build the system from sources. They are verified in continuous integration on Ubuntu 22.04, 24.04 and 26.04 (on the Intel/AMD x86_64 architecture). Debian 13 (Trixie) works in exactly the same way; the package names below are identical on Debian.

Install the build tools and libraries. These include the C/C++ compiler, Berkeley DB, the Boost libraries, a Java Development Kit (default-jdk) for the Java GUI, and SWI-Prolog for the optimizer:

sudo apt-get update
sudo apt-get install flex bison gcc g++ build-essential \
    libdb5.3 libdb5.3-dev libdb5.3++ libdb5.3++-dev db5.3-util \
    libjpeg-dev libgsl0-dev libreadline-dev librecode-dev \
    libgmp-dev libgmp10 libncurses-dev libxml2-dev libboost-all-dev \
    libbison-dev libfl-dev libquadmath0 nlohmann-json3-dev \
    default-jdk swi-prolog swi-prolog-nox

Set up the build environment. The build environment (compiler, Berkeley DB, SWI-Prolog paths, ...) is derived automatically. So, there are only these settings:

export SECONDO_BUILD_DIR=$HOME/secondo
export SECONDO_CONFIG=$SECONDO_BUILD_DIR/bin/SecondoConfig.ini
export PATH="$PATH:$SECONDO_BUILD_DIR/bin:$SECONDO_BUILD_DIR/Tools/pd"

It is convenient to add these lines to your ~/.bashrc, so the environment is set up automatically in every new terminal:

echo 'export SECONDO_BUILD_DIR=$HOME/secondo' >> ~/.bashrc
echo 'export SECONDO_CONFIG=$SECONDO_BUILD_DIR/bin/SecondoConfig.ini' >> ~/.bashrc
echo 'export PATH="$PATH:$SECONDO_BUILD_DIR/bin:$SECONDO_BUILD_DIR/Tools/pd"' >> ~/.bashrc

Download the sources as described on the Sources page.
Build the system by running make in $SECONDO_BUILD_DIR.
```
cd $SECONDO_BUILD_DIR
make -j $(nproc)
```

Installation on macOS

On macOS, all tools required by Secondo are installed with the Homebrew package manager — a separate SDK download is no longer needed. The steps below are verified on macOS 15 (Sequoia) and macOS 26 (Tahoe), on both Intel (x86_64) and Apple Silicon (arm64). Enter the commands in a terminal.

Install the Xcode command line tools (C/C++ compiler, make, system headers):
```
xcode-select --install
```

Install Homebrew (skip if it is already present); see brew.sh:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install the build tools and libraries. These include SWI-Prolog for the optimizer and a Java Development Kit for the Java GUI:
```
brew install flex bison berkeley-db gsl jpeg-turbo boost gmp \
     libxml2 readline nlohmann-json swi-prolog openjdk@21
```
Homebrew's flex, bison and openjdk@21 are "keg-only" and are not put on the PATH automatically. Add flex and bison to your ~/.zshrc:
```
echo 'export PATH="$(brew --prefix bison)/bin:$(brew --prefix flex)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
For the JDK, follow the caveats printed by Homebrew to make it visible to the system (or install an equivalent JDK 21, e.g. Temurin).

Set up the build environment. The build environment (compiler, Berkeley DB, SWI-Prolog paths, ...) is derived automatically. So, there are only these settings:

export SECONDO_BUILD_DIR=$HOME/secondo
export SECONDO_CONFIG=$SECONDO_BUILD_DIR/bin/SecondoConfig.ini
export PATH="$PATH:$SECONDO_BUILD_DIR/bin:$SECONDO_BUILD_DIR/Tools/pd"

It is convenient to add these lines to your ~/.zshrc, so the environment is set up automatically in every new terminal:

echo 'export SECONDO_BUILD_DIR=$HOME/secondo' >> ~/.zshrc
echo 'export SECONDO_CONFIG=$SECONDO_BUILD_DIR/bin/SecondoConfig.ini' >> ~/.zshrc
echo 'export PATH="$PATH:$SECONDO_BUILD_DIR/bin:$SECONDO_BUILD_DIR/Tools/pd"' >> ~/.zshrc

Download the sources as described on the Sources page.

Build the system by running make in $SECONDO_BUILD_DIR.

cd $SECONDO_BUILD_DIR
make -j $(sysctl -n hw.ncpu)

Upgrading the macOS version

After an upgrade of the macOS operating system, the Xcode developer tools have to be reinstalled. If you have upgraded your system and the call of make produces the following error message:

xcrun: error: invalid active developer path

then you have to reinstall the Xcode developer tools. To do so, start a terminal and enter:

xcode-select --install

In the upcoming dialog, click on the button Install and wait until the installation is finished. After that, the make process should run as before.

Installation Guides for Historical Distributions

Older operating-system releases (Fedora, SuSE, and older Ubuntu versions) were installed with per-version scripts that are no longer maintained. They are kept for reference on the historical installation guides page.