• Linux systems: Yade can be installed from packages (pre-compiled binaries) or source code. The choice depends on what you need: if you don’t plan to modify Yade itself, package installation is easier. In the contrary case, you must download and install the source code.
  • Other Operating Systems: Jump to the last section of this page.
  • 64 bit Operating Systems required; no support for 32 bit (i386).


Stable packages

Since 2011, all Ubuntu (starting from 11.10, Oneiric) and Debian (starting from Wheezy) versions have Yade in their main repositories. There are only stable releases in place. To install Yade, run the following:

sudo apt-get install yade

After that you can normally start Yade using the command yade or yade-batch.

This image shows versions and up to date status of Yade in some repositories.

Yade versions in different repositories

Daily packages

Pre-built packages updated more frequently than the stable versions are provided for all currently supported Debian and Ubuntu versions and available on .

These are “daily” versions of the packages which are being updated regularly and, hence, include all the newly added features.

To install the daily-version you need to add the repository to your /etc/apt/sources.list.

  • Debian 9 stretch:

    sudo bash -c 'echo "deb stretch main" >> /etc/apt/sources.list'
  • Debian 10 buster:

    sudo bash -c 'echo "deb buster main" >> /etc/apt/sources.list'
  • Debian 11 bullseye:

    sudo bash -c 'echo "deb bullseye main" >> /etc/apt/sources.list'
  • Debian 12 bookworm also with high precision long double, float128 and mpfr150 packages:

    sudo bash -c 'echo "deb bookworm main" >> /etc/apt/sources.list'
  • Ubuntu 16.04 xenial:

    sudo bash -c 'echo "deb xenial main" >> /etc/apt/sources.list'
  • Ubuntu 18.04 bionic:

    sudo bash -c 'echo "deb bionic main" >> /etc/apt/sources.list'
  • Ubuntu 20.04 focal:

    sudo bash -c 'echo "deb focal main" >> /etc/apt/sources.list'
  • Ubuntu 22.04 jammy also with high precision long double, float128 and mpfr150 packages:

    sudo bash -c 'echo "deb jammy main" >> /etc/apt/sources.list'

Add the PGP-key AA915EEB as trusted and install yadedaily:

wget -O - | sudo apt-key add -
sudo apt-get update
sudo apt-get install yadedaily

After that you can normally start Yade using the command yadedaily or yadedaily-batch. yadedaily on older distributions can have some disabled features due to older library versions, shipped with particular distribution.

The Git-repository for packaging stuff is available on GitLab.

If you do not need yadedaily-package anymore, just remove the corresponding line in /etc/apt/sources.list and the package itself:

sudo apt-get remove yadedaily

To remove our key from keyring, execute the following command:

sudo apt-key remove AA915EEB

Daily and stable Yade versions can coexist without any conflicts, i.e., you can use yade and yadedaily at the same time.


Yade can be installed using docker images, which are daily built. Images contain both stable and dialy versions of packages. Docker images are based on supported distributions:

  • Debian 9 stretch:

    docker run -it
  • Debian 10 buster:

    docker run -it
  • Debian 11 bullseye:

    docker run -it
  • Debian 12 bookworm:

    docker run -it
  • Ubuntu 16.04 xenial:

    docker run -it
  • Ubuntu 18.04 bionic:

    docker run -it
  • Ubuntu 20.04 focal:

    docker run -it
  • Ubuntu 22.04 jammy:

    docker run -it

After the container is pulled and is running, Yade functionality can be checked:

yade --test
yade --check
yadedaily --test
yadedaily --check

Source code

Installation from source code is reasonable, when you want to add or modify constitutive laws, engines, functions etc. Installing the latest trunk version allows one to use newly added features, which are not yet available in packaged versions.


If you want to install from source, you can install either a release (numbered version, which is frozen) or the current development version (updated by the developers frequently). You should download the development version (called trunk) if you want to modify the source code, as you might encounter problems that will be fixed by the developers. Release versions will not be updated (except for updates due to critical and easy-to-fix bugs), but generally they are more stable than the trunk.

  1. Releases can be downloaded from the download page, as compressed archive. Uncompressing the archive gives you a directory with the sources.
  2. The development version (trunk) can be obtained from the code repository at GitLab.

We use GIT (the git command) for code management (install the git package on your system and create a GitLab account):

git clone

will download the whole code repository of the trunk. Check out Yade on GitLab for more details on how to collaborate using git.

Alternatively, a read-only checkout is possible via https without a GitLab account (easier if you don’t want to modify the trunk version):

git clone

For those behind a firewall, you can download the sources from our GitLab repository as compressed archive.

Release and trunk sources are compiled in exactly the same way.


Yade relies on a number of external software to run; they are checked before the compilation starts. Some of them are only optional.

  • cmake build system
  • gcc compiler (g++); other compilers will not work; you need g++>=4.2 for openMP support
  • boost 1.47 or later
  • Qt library
  • freeglut3
  • libQGLViewer
  • python, numpy, ipython, sphinx, mpi4py
  • matplotlib
  • eigen algebra library (minimal required version 3.2.1)
  • gdb debugger
  • sqlite3 database engine
  • VTK library (optional but recommended)
  • CGAL library (optional)
  • SuiteSparse sparse algebra library (fluid coupling, optional, requires eigen>=3.1)
  • OpenBLAS optimized and parallelized alternative to the standard blas+lapack (fluid coupling FlowEngine, optional)
  • Metis matrix preconditioning (fluid coupling, optional)
  • OpenMPI library for parallel distributed computing (For MPI and OpenFOAM coupling, optional)
  • python3-mpi4py MPI for Python (For MPI, optional)
  • coin-or COIN-OR Linear Programming Solver (For PotentialBlock, optional)
  • mpfr in C++ and mpmath in python for high precision Real or for CGAL exact predicates (optional)
  • mpc is an MPFR extension to complex numbers. It is used explicitly together with MPFR.

Most of the list above is very likely already packaged for your distribution. In case you are confronted with some errors concerning not available packages (e.g., package libmetis-dev is not available) it may be necessary to add yade external ppa from (see below) as well as (see the top of this page):

sudo add-apt-repository ppa:yade-users/external
sudo apt-get update

The following commands have to be executed in the command line of your corresponding distribution. Just copy&paste to the terminal. Note, to execute these commands you need root privileges.

  • Ubuntu 20.04, 18.04, Debian 9, 10, 11 and their derivatives:

    sudo apt install cmake git freeglut3-dev libloki-dev libboost-all-dev fakeroot \
    dpkg-dev build-essential g++ python3-dev python3-ipython python3-matplotlib \
    libsqlite3-dev python3-numpy python3-tk gnuplot libgts-dev python3-pygraphviz \
    libvtk6-dev libeigen3-dev python3-xlib python3-pyqt5 pyqt5-dev-tools python3-mpi4py \
    python3-pyqt5.qtwebkit gtk2-engines-pixbuf python3-pyqt5.qtsvg libqglviewer-dev-qt5 \
    python3-pil libjs-jquery python3-sphinx python3-git libxmu-dev libxi-dev libcgal-dev \
    help2man libbz2-dev zlib1g-dev libopenblas-dev libsuitesparse-dev \
    libmetis-dev python3-bibtexparser python3-future coinor-clp coinor-libclp-dev \
    python3-mpmath libmpfr-dev libmpfrc++-dev libmpc-dev
  • For Ubuntu 16.04 libqglviewer-dev-qt5 is to be replaced by libqglviewer-dev and python3-ipython by ipython3.

  • The packages python3-mpmath libmpfr-dev libmpfrc++-dev in above list are required only if one wants to use high precision calculations. The latter two only if mpfr will be used. See high precision documentation for more details.

  • For building documentation (the make doc invocation explained below) additional package texlive-xetex is required. On some multi-language systems an error Building format(s) --all. This may take some time... fmtutil failed. may occur, in that case a package locales-all is required.

Some of the packages (for example, cmake, eigen3) are mandatory, some of them are optional. Watch for notes and warnings/errors, which are shown by cmake during the configuration step. If the missing package is optional, some of Yade features will be disabled (see the messages at the end of the configuration).

Some packages listed here are relatively new and they can be absent in your distribution (for example, libmetis-dev). They can be installed from or from our external PPA. If not installed the related features will be disabled automatically.

If you are using other distributions than Debian or its derivatives you should install the software packages listed above. Their names in other distributions can differ from the names of the Debian-packages.


If you have Ubuntu 14.04 Trusty, you need to add -DCMAKE_CXX_FLAGS=-frounding-math during the configuration step of compilation (see below) or to install libcgal-dev from our external PPA. Otherwise the following error occurs on AMD64 architectures:

terminate called after throwing an instance of 'CGAL::Assertion_exception'
what():  CGAL ERROR: assertion violation!
Expr: -CGAL_IA_MUL(-1.1, 10.1) != CGAL_IA_MUL(1.1, 10.1)
File: /usr/include/CGAL/Interval_nt.h
Line: 209
Explanation: Wrong rounding: did you forget the  -frounding-math  option if you use GCC (or  -fp-model strict  for Intel)?


You should create a separate build-place-folder, where Yade will be configured and where the source code will be compiled. Here is an example for a folder structure:

myYade/                 ## base directory
        trunk/          ## folder for source code in which you use git
        build/          ## folder in which the sources will be compiled; build-directory; use cmake here
        install/        ## install folder; contains the executables

Then, inside this build-directory you should call cmake to configure the compilation process:

cmake -DCMAKE_INSTALL_PREFIX=/path/to/installfolder /path/to/sources

For the folder structure given above call the following command in the folder “build”:

cmake -DCMAKE_INSTALL_PREFIX=../install ../trunk

Additional options can be configured in the same line with the following syntax:


For example:


The following cmake options are available: (see the source code for a most up-to-date list)

  • CMAKE_INSTALL_PREFIX: path where Yade should be installed (/usr/local by default)
  • LIBRARY_OUTPUT_PATH: path to install libraries (lib by default)
  • DEBUG: compile in debug-mode (OFF by default)
  • MAX_LOG_LEVEL: set maximum level for LOG_* macros compiled with ENABLE_LOGGER, (default is 5)
  • CMAKE_VERBOSE_MAKEFILE: output additional information during compiling (OFF by default)
  • SUFFIX: suffix, added after binary-names (version number by default)
  • NOSUFFIX: do not add a suffix after binary-name (OFF by default)
  • YADE_VERSION: explicitly set version number (is defined from git-directory by default)
  • ENABLE_ASAN: AddressSanitizer allows detection of memory errors, memory leaks, heap corruption errors and out-of-bounds accesses (but it is slow)
  • ENABLE_CGAL: enable CGAL option (ON by default)
  • ENABLE_COMPLEX_MP: use boost multiprecision complex for ComplexHP<N>, otherwise use std::complex<RealHP<N>>. See high precision documentation for additional details. (ON by default if possible: requires boost >= 1.71)
  • ENABLE_DEFORM: enable constant volume deformation engine (OFF by default)
  • ENABLE_FAST_NATIVE: use maximum optimization compiler flags including -Ofast and -mtune=native. Note: native means that code will only run on the same processor type on which it was compiled. Observed speedup was 2% (below standard deviation measurement error) and above 5% if clang compiler was used. (OFF by default)
  • ENABLE_FEMLIKE: enable meshed solids, FEM-like (ON by default)
  • ENABLE_GL2PS: enable GL2PS-option (ON by default)
  • ENABLE_GTS: enable GTS-option (ON by default)
  • ENABLE_GUI: enable GUI option (ON by default)
  • ENABLE_LBMFLOW: enable LBMFLOW-option, LBM_ENGINE (ON by default)
  • ENABLE_LS_DEM: enable a LevelSet shape description (ON by default)
  • ENABLE_LINSOLV: enable LINSOLV-option (ON by default)
  • ENABLE_LIQMIGRATION: enable LIQMIGRATION-option, see [Mani2013] for details (OFF by default)
  • ENABLE_LOGGER: use boost::log library for logging separately for each class (ON by default)
  • ENABLE_MASK_ARBITRARY: enable MASK_ARBITRARY option (OFF by default)
  • ENABLE_MPFR: use mpfr in C++ and mpmath in python. It can be used for higher precision Real or for CGAL exact predicates (OFF by default)
  • ENABLE_MPI: Enable MPI enviroment and communication, required distributed memory and for Yade-OpenFOAM coupling (ON by default)
  • ENABLE_OAR: generate a script for oar-based task scheduler (OFF by default)
  • ENABLE_OPENMP: enable OpenMP-parallelizing option (ON by default)
  • ENABLE_PARTIALSAT : enable the partially saturated clay engine, under construction (ON by default)
  • ENABLE_PFVFLOW: enable PFVFLOW-option, FlowEngine (ON by default)
  • ENABLE_POTENTIAL_BLOCKS: enable potential blocks option (ON by default)
  • ENABLE_POTENTIAL_PARTICLES: enable potential particles option (ON by default)
  • ENABLE_PROFILING: enable profiling, e.g., shows some more metrics, which can define bottlenecks of the code (OFF by default)
  • ENABLE_REAL_HP: allow using twice, quadruple or higher precisions of Real as RealHP<2>, RealHP<4> or RealHP<N> in computationally demanding sections of C++ code. See high precision documentation for additional details (ON by default).
  • ENABLE_SPH: enable SPH-option, Smoothed Particle Hydrodynamics (OFF by default)
  • ENABLE_THERMAL : enable thermal engine (ON by default, experimental)”
  • ENABLE_TWOPHASEFLOW: enable TWOPHASEFLOW-option, TwoPhaseFlowEngine (ON by default)
  • ENABLE_USEFUL_ERRORS: enable useful compiler errors which help a lot in error-free development (ON by default)
  • ENABLE_VTK: enable VTK-export option (ON by default)
  • REAL_PRECISION_BITS, REAL_DECIMAL_PLACES: specify either of them to use a custom calculation precision of Real type. By default double (64 bits, 15 decimal places) precision is used as the Real type. See high precision documentation for additional details.
  • runtimePREFIX: used for packaging, when install directory is not the same as runtime directory (/usr/local by default)
  • VECTORIZE: enables vectorization and alignment in Eigen3 library, experimental (OFF by default)
  • USE_QT5: use QT5 for GUI (ON by default)
  • CHOLMOD_GPU link Yade to custom SuiteSparse installation and activate GPU accelerated PFV (OFF by default)
  • SUITESPARSEPATH: define this variable with the path to a custom suitesparse install
  • PYTHON_VERSION: force Python version to the given one, e.g. -DPYTHON_VERSION=3.5. Set to -1 to automatically use the last version on the system (-1 by default)

It is possible to disable all options to create the slim build:


In this case all available options will be switched off. In this case some required options can be enabled explicitely:


For using more extended parameters of cmake, please follow the corresponding documentation on


Only Qt5 is supported. On Debian/Ubuntu operating systems libQGLViewer of version 2.6.3 and higher are compiled against Qt5 (for other operating systems refer to the package archive of your distribution). If you mix Qt-versions a Segmentation fault will appear just after Yade is started. To provide necessary build dependencies for Qt5, install python-pyqt5 pyqt5-dev-tools.

If cmake finishes without errors, you will see all enabled and disabled options at the end. Then start the actual compilation process with:


The compilation process can take a considerable amount of time, be patient. If you are using a multi-core systems you can use the parameter -j to speed-up the compilation and split the compilation onto many cores. For example, on 4-core machines it would be reasonable to set the parameter -j4. Note, Yade requires approximately 3GB RAM per core for compilation, otherwise the swap-file will be used and compilation time dramatically increases.

The installation is performed with the following command:

make install

The install command will in fact also recompile if source files have been modified. Hence there is no absolute need to type the two commands separately. You may receive make errors if you don’t have permission to write into the target folder. These errors are not critical but without writing permissions Yade won’t be installed in /usr/local/bin/.

After the compilation finished successfully, the new built can be started by navigating to /path/to/installfolder/bin and calling yade via (based on version yade-2014-02-20.git-a7048f4):

cd /path/to/installfolder/bin

For building the documentation you should at first execute the command make install and then make doc to build it. The generated files will be stored in your current install directory /path/to/installfolder/share/doc/yade-your-version. Once again writing permissions are necessary for installing into /usr/local/share/doc/. To open your local documentation go into the folder html and open the file index.html with a browser.

make manpage command generates and moves manpages in a standard place. make check command executes standard test to check the functionality of the compiled program.

Yade can be compiled not only by GCC-compiler, but also by CLANG front-end for the LLVM compiler. For that you set the environment variables CC and CXX upon detecting the C and C++ compiler to use:

export CC=/usr/bin/clang
export CXX=/usr/bin/clang++

Clang does not support OpenMP-parallelizing for the moment, that is why the feature will be disabled.

Supported linux releases

Currently supported [1] linux releases and their respective docker files are:

These are the bash commands used to prepare the linux distribution and environment for installing and testing yade. These instructions are automatically performed using the gitlab continuous integration service after each merge to master. This makes sure that yade always works correctly on these linux distributions. In fact yade can be installed manually by following step by step these instructions in following order:

  1. Bash commands in the respective Dockerfile to install necessary packages,
  2. do git clone,
  3. then the cmake_* commands in the .gitlab-ci.yml file for respective distribution,
  4. then the make_* commands to compile yade,
  5. and finally the --check and --test commands.
  6. Optionally documentation can be built with make doc command, however currently it is not guaranteed to work on all linux distributions due to frequent interface changes in sphinx.

These instructions use ccache and to speed-up compilation as described below.

[1]To see details of the latest build log click on the master branch.

Python 2 backward compatibility

Following the end of Python 2 support (beginning of 2020), Yade compilation on a Python 2 ecosystem is no longer garanteed since the 6e097e95 trunk version. Python 2-compilation of the latter is still possible using the above PYTHON_VERSION cmake option, requiring Python 2 version of prerequisites packages whose list can be found in the corresponding paragraph (Python 2 backward compatibility) of the historical doc.

Ongoing development of Yade now assumes a Python 3 environment, and you may refer to some notes about converting Python 2 scripts into Python 3 if needed.

Speed-up compilation

Compile with ccache

Caching previous compilations with ccache can significantly speed up re-compilation:

cmake -DCMAKE_CXX_COMPILER_LAUNCHER=ccache [options as usual]

Additionally one can check current ccache status with command ccache --show-stats (ccache -s for short) or change the default cache size stored in file ~/.ccache/ccache.conf.

Compile with distcc

When spliting the compilation on many cores (make -jN), N is limited by the available cores and memory. It is possible to use more cores if remote computers are available, distributing the compilation with distcc (see distcc documentation for configuring slaves and master):

export CC="distcc gcc"
export CXX="distcc g++"
cmake [options as usual]
make -jN

The two tools can be combined, adding to the above exports:

export CCACHE_PREFIX="distcc"

Compile with cmake UNITY_BUILD

This option concatenates source files in batches containing several *.cpp each, in order to share the overhead of include directives (since most source files include the same boost headers, typically). It accelerates full compilation from scratch (quite significantly). It is activated by adding the following to cmake command, CMAKE_UNITY_BUILD_BATCH_SIZE defines the maximum number of files to be concatenated together (the higher the better, main limitation might be available RAM):


This method is helpless for incremental re-compilation and might even be detrimental since a full batch has to be recompiled each time a single file is modified. If it is anticipated that specific files will need incremental compilation they can be excluded from the unity build by assigning their full path to cmake flag NO_UNITY (a single file or a comma-separated list):

-DCMAKE_UNITY_BUILD=ON -DCMAKE_UNITY_BUILD_BATCH_SIZE=18 -DNO_UNITY=../trunk/pkg/dem/CohesiveFrictionalContactLaw.cpp

Cloud Computing

It is possible to exploit cloud computing services to run Yade. The combo Yade/Amazon Web Service has been found to work well, namely. Detailed instructions for migrating to amazon can be found in the section Using YADE with cloud computing on Amazon EC2.

GPU Acceleration

The FlowEngine can be accelerated with CHOLMOD’s GPU accelerated solver. The specific hardware and software requirements are outlined in the section Accelerating Yade’s FlowEngine with GPU.

Special builds

The software can be compiled by a special way to find some specific bugs and problems in it: memory corruptions, data races, undefined behaviour etc.

The listed sanitizers are runtime-detectors. They can only find the problems in the code, if the particular part of the code is executed. If you have written a new C++ class (constitutive law, engine etc.) try to run your Python script with the sanitized software to check, whether the problem in your code exist.


AddressSanitizer is a memory error detector, which helps to find heap corruptions, out-of-bounds errors and many other memory errors, leading to crashes and even wrong results.

To compile Yade with this type of sanitizer, use ENABLE_ASAN option:


The compilation time, memory consumption during build and the size of build-files are much higher than during the normall build. Monitor RAM and disk usage during compilation to prevent out-of-RAM problems.

To find the proper libasan library in your particular distribution, use locate or find /usr -iname "libasan*so" command. Then, launch your yade executable in connection with that libasan library, e.g.:

LD_PRELOAD=/some/path/to/ yade

By default the leak detector is enabled in the asan build. Yade is producing a lot of leak warnings at the moment. To mute those warnings and concentrate on other memory errors, one can use detect_leaks=0 option. Accounting for the latter, the full command to run tests with the AddressSanitized-Yade on Debian 10 Buster is:

ASAN_OPTIONS=detect_leaks=0:verify_asan_link_order=false yade --test

If you add a new check script, it is being run automatically through the AddressSanitizer in the CI-pipeline.


If you are not running a Linux system there is a way to create an Ubuntu live-usb on any usb mass-storage device (minimum size 10GB). It is a way to boot the computer on a linux system with Yadedaily pre-installed without affecting the original system. More informations about this alternative are available here (see the README file first).

Alternatively, images of a linux virtual machine can be downloaded, here again, and they should run on any system with a virtualization software (tested with VirtualBox and VMWare).