Installation

Conjure can be installed either by downloading a binary distribution, or by compiling it from source code.

It can also be used directly via a container that we release on GitHub. This is the suggested way of using Conjure, see Quick start using containers and Docker / Podman / Apptainer below.

Why containers are recommended

Using Conjure via a container avoids the need to install and manage its dependencies locally, including Savile Row and backend solvers. Containers also make it easy to pin exact versions of Conjure and solvers, ensuring reproducibility across machines and over time. For most users, especially when running experiments or teaching, containers provide the simplest and most robust setup.

Quick start using containers

If you have Docker, Podman, or Apptainer working locally, the simplest way to use Conjure is to install a small wrapper script that runs Conjure inside a container. This makes conjure available as a normal command, both interactively and from scripts.

The examples below install the wrapper in ~/.local/bin. Make sure this directory is on your ``PATH``.

In the Docker and Podman commands below, the directory named by the TMPDIR environment variable is mounted to /tmp in the container, so Conjure writes temporaries on the host where you expect. Invoke Docker or Podman from a shell where TMPDIR is set and non-empty (many environments do this for you; if not, export a suitable directory first).

Docker

# create the directory if it doesn't exist
mkdir -p ~/.local/bin

# create the conjure wrapper
printf '#!/bin/sh\ndocker run --rm -v "$PWD:/work" -v "$TMPDIR:/tmp" -w /work ghcr.io/conjure-cp/conjure:v2.6.0 conjure "$@"\n' > ~/.local/bin/conjure

# make it executable
chmod +x ~/.local/bin/conjure

Podman

# create the directory if it doesn't exist
mkdir -p ~/.local/bin

# create the conjure wrapper
printf '#!/bin/sh\npodman run --rm -v "$PWD:/work:z" -v "$TMPDIR:/tmp:z" -w /work ghcr.io/conjure-cp/conjure:v2.6.0 conjure "$@"\n' > ~/.local/bin/conjure

# make it executable
chmod +x ~/.local/bin/conjure

Apptainer

# create the directory if it doesn't exist
mkdir -p ~/.local/bin

# create the conjure wrapper
printf '#!/bin/sh\napptainer exec docker://ghcr.io/conjure-cp/conjure:v2.6.0 conjure "$@"\n' > ~/.local/bin/conjure

# make it executable
chmod +x ~/.local/bin/conjure

The container will be downloaded first time you run the conjure command defined this way.

Verify the installation

After installation, verify that Conjure is available:

conjure --version

You can also verify that the installed solvers are all operational:

# download a small bundle of files, we will use this to test the installation
wget https://github.com/conjure-cp/conjure/releases/download/v2.6.0/conjure-allsolvers-test-v2.6.0.zip

# run the test
unzip conjure-allsolvers-test-v2.6.0.zip && bash test.sh

test.sh should produce a bunch of output and include “Pass!” as the last line.

Note that this quick start guide is not a replacement for the complete installation instructions; please keep reading to learn more.

Downloading a binary

Conjure releases for Linux and macOS ship as zip archives. For most users, the recommended download is the *-with-solvers.zip archive, which contains Conjure, Savile Row, and the bundled open-source solvers. The smaller archive without -with-solvers only contains the conjure executable, so you will need to install Savile Row and any solver binaries separately.

If it is available for your platform, you can download the latest release, extract the archive, and add the extracted directory to your PATH.

Assuming you extract conjure-v2.6.0-linux-with-solvers.zip to ~/work:

export PATH="$HOME/work/conjure-v2.6.0-linux-with-solvers:$PATH"

The top-level commands in the extracted *-with-solvers directory are wrappers that keep solver lookup, shared-library search paths, and the MiniZinc standard library rooted inside the extracted bundle. When you run those top-level commands directly from the extracted bundle, you do not need to set LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, or MZN_STDLIB_DIR yourself. If you copy individual binaries out of the bundle or bypass the top-level wrappers, that no longer applies.

For macOS, remove the quarantine attribute from the extracted directory before running the bundled tools:

xattr -dr com.apple.quarantine "$HOME/work/conjure-v2.6.0-macos-with-solvers"

You will also need a Java runtime for Savile Row. On macOS, we recommend Homebrew and Amazon Corretto:

brew install --cask corretto

On Linux, install a recent Java runtime using your distribution’s package manager.

For Windows, please use the Linux binaries with the Windows Subsystem for Linux.

To install into WSL2:

cd
wget https://github.com/conjure-cp/conjure/releases/download/v2.6.0/conjure-v2.6.0-linux-with-solvers.zip
unzip conjure-v2.6.0-linux-with-solvers.zip
echo 'export PATH="$HOME/conjure-v2.6.0-linux-with-solvers:$PATH"' >> ~/.bashrc

Then restart your shell.

Compiling from source

To compile Conjure yourself, download the source code from GitHub.

git clone https://github.com/conjure-cp/conjure.git
cd conjure
BIN_DIR=/somewhere/in/your/path make install

Conjure is implemented in Haskell and can be compiled using either cabal-install or stack.

It comes with a Makefile which will use Stack by default. The default target in the Makefile will install Stack using the standard procedures (which involves downloading and running a script). For more precise control, you might want to consider installing the Haskell tools beforehand instead of using the Makefile.

In addition, a number of supported backend solvers can be compiled using the make solvers target. This target also takes a BIN_DIR environment variable to control the location of the solver executables, and a PROCESSES environment variable to control how many processes to use when building solvers

BIN_DIR=/somewhere/in/your/path PROCESSES=4 make solvers

Installing Savile Row

Since Conjure works by generating an Essence’ model, Savile Row is a vital tool when using it. You do not need to download Savile Row separately when you compile Conjure from source or download a *-with-solvers bundle or use a container-based installation. An up-to-date version of Savile Row is provided in these cases.

A standalone version of Savile Row and user documentation for Savile Row can be downloaded from its website.

Docker / Podman / Apptainer

Conjure is distributed as a container image via the GitHub Container Registry. Using a container allows Conjure (together with Savile Row and supported solvers) to be run without a local installation, and makes it easy to pin a specific version for reproducibility.

The container image includes:

conjure
savilerow
almost all supported solvers

Available images

Latest release:

ghcr.io/conjure-cp/conjure:latest
A specific release:

ghcr.io/conjure-cp/conjure:v2.6.0
Latest commit on main (development version):

ghcr.io/conjure-cp/conjure:main
Immutable image (recommended for reproducibility):

ghcr.io/conjure-cp/conjure@sha256:VERSION

See all available images at: https://github.com/conjure-cp/conjure/pkgs/container/conjure

Docker and Podman usage

The examples below assume:

Docker or Podman is installed and running
The current directory contains: - an Essence model (e.g. test.essence) - a parameter file (e.g. sample.param)

Docker:

docker run --rm \
  -v "$PWD:/work" \
  -v "$TMPDIR:/tmp" \
  -w /work \
  ghcr.io/conjure-cp/conjure:v2.6.0 \
  conjure solve test.essence sample.param

Podman:

podman run --rm \
  -v "$PWD:/work:z" \
  -v "$TMPDIR:/tmp:z" \
  -w /work \
  ghcr.io/conjure-cp/conjure:v2.6.0 \
  conjure solve test.essence sample.param

Note that :z above is for handling SELinux. A side-effect of this is that you will not be able to run this Podman command inside your home directory. If you try to do so, you will get the following error message: “Error: SELinux relabeling of <your home directory> is not allowed”.

Apptainer usage

apptainer exec docker://ghcr.io/conjure-cp/conjure:v2.6.0 \
  conjure solve test.essence sample.param

You normally do not need the Docker/Podman -v "$TMPDIR:/tmp" bind with Apptainer: in the default configuration it already bind-mounts the host /tmp into the container, so /tmp inside the container is the host /tmp.

Version pinning

For fully reproducible experiments, use a fixed version tag or a SHA-based image reference.

Authentication note (GHCR)

If pulling the image fails with an error such as:

denied: denied

this is usually caused by cached credentials for ghcr.io. Logging out and retrying typically resolves the issue:

docker logout ghcr.io

or the equivalent command for Podman.

Apptainer does not use Docker/Podman credential stores and does not provide a logout command.

Testing your installation

Each release ships a solver smoke-test bundle called conjure-allsolvers-test-v2.6.0.zip.

If you installed one of the wrappers above, conjure is already on your PATH and you can run the tests directly:

bash test.sh

On success you will see Pass! and a zero exit code.

Container-only execution (no wrapper):

docker run --rm \
  -v "$PWD:/work" \
  -v "$TMPDIR:/tmp" \
  -w /work \
  ghcr.io/conjure-cp/conjure:v2.6.0 \
  bash test.sh

podman run --rm \
  -v "$PWD:/work:z" \
  -v "$TMPDIR:/tmp:z" \
  -w /work \
  ghcr.io/conjure-cp/conjure:v2.6.0 \
  bash test.sh

apptainer exec docker://ghcr.io/conjure-cp/conjure:v2.6.0 \
  bash test.sh

CPLEX with Docker/Podman

CPLEX is a commercial mathemathical programming solver that is supported by Conjure. However we cannot provide CPLEX as part of the container image due to its license. Instead, we include instructions here for building another image that contains CPLEX as well.

Obtain a commercial or academic license for CPLEX. Use the instructions on its website. Notes on this post are helpful too.

We assume you are on a Linux system here, though steps for macOS are very similar.

Download the installer. A file called cplex_studio2211.linux_x86_64.bin.
Run the installer and follow the instructions.
You can install CPLEX to its default location, however a user-level install is also possible. Assuming you installed it at: /home/USER/cplex-install for the remaining instructions
Create a file called /home/USER/cplex-install/Dockerfile with the following contents

FROM ghcr.io/conjure-cp/conjure@sha256:VERSION
COPY cplex /root/.local/cplex
ENV CPLEX_PATH /root/.local/cplex/bin/x86-64_linux/libcplex2211.so

In the /home/USER/cplex-install directory execute: podman build -t conjure-cplex .
podman images should now list localhost/conjure-cplex as well as a bunch of other images.
You can replace podman with docker in the last 2 commands to use docker instead.