After installing EasyBuild, you should configure it.
EasyBuild should work fine out-of-the-box if you use Lmod as your modules tool. If you are not using Lmod, please see here for more information.
Nevertheless, we strongly recommend you to inspect the default configuration, and to configure EasyBuild according to your preferences and the system on which you will use it.
Available configuration settings¶
One of the central policies in the EasyBuild project is to avoid hardcoded settings in the codebase. While this significantly increases the ability to configure EasyBuild to your liking, it also results in a large amount of available configuration settings.
The full list of configuration settings can be consulted via
which shows the corresponding command line option accompanied by a short description.
At the time of writing, about 270 different configuration settings are supported by EasyBuild.
For the sake of this tutorial we will focus on a specific subset of configuration settings, and cover only the most prominent and important ones.
We will refer to EasyBuild configuration settings using the names as they appears in the output of
and omit the leading dashes (
--) for the sake of clarity.
Keep in mind that every configuration setting can be defined in 3 different ways, see below for more details.
prefix configuration setting specifies the overall prefix that EasyBuild should use,
which determines the default value for various other configuration settings:
<prefix> represents the value of the
prefix configuration setting.
If one of the configuration settings affected by
prefix is defined specifically,
prefix value becomes irrelevant for that specific configuration setting.
The location for both the software installation directories and generated module files
can be controlled via the
installpath configuration setting.
Software installation directories will be placed in
<installpath>/modules/all will be used for generated module files.
installpath location is usually set to a directory on a shared filesystem when installing
software for an HPC cluster. Of course, software can also be installed on a local filesystem,
which can be useful to test and evaluate software installations.
Separate configuration settings are available for both software and modules locations,
as well as for controlling the name of the
We recommend to only change the
installpath configuration setting to control the location
of software installations and accompanying module files,
such that the software and modules directories are located in the same parent directory,
and the default
modules/all names for the subdirectories are used.
For each installation it performs, EasyBuild creates a separate build directory where software will be compiled
before installing it. This directory is cleaned up automatically when the installation is successfully completed.
To control the location where these build directories are created, you can use the
buildpath configuration setting.
Keep in mind that build directories may grow out to several GBs in size during an installation, and that the commands that run in there can be fairly I/O-intensive since they may involve manipulating lots of small files. In addition, a build directory that corresponds to a failing installation is not cleaned up automatically, but it will be cleaned up and recycled when the same installation is re-attempted. Running out of disk space in the location where build directories are created will result in failing installations.
It is strongly recommend to use the path to a directory on a local filesystem for the value of the
buildpath configuration setting, since using a shared filesystem like Lustre or GPFS is known to cause
problems when building certain software packages. Using an in-memory location (like
significantly speed up the build process, but may also lead to problems (due to space limitations,
or specific mount options like
Use a directory on a local filesystem for
buildpath for this tutorial.
In addition, try to ensure you use a path that will not be used by other users on the same system,
/tmp/$USER, for example.
For most supported software, EasyBuild can automatically download the source files required for the installation. Before trying to download a source file, EasyBuild will first check if it is already present in the source path.
The locations considered by EasyBuild when checking for available source files, as well as the location to
store downloaded source files, can be controlled via the
sourcepath configuration setting.
sourcepath value is a colon (
:) separated list of directory paths.
Each of these paths will be considered in turn when checking for available source files,
until one of them provides the desired source file. Searching for source files is done
based on filename, and a couple of subdirectories are considered.
For example, for a software package named '
Example', EasyBuild will consider locations like
<sourcepath>/Example/, and so on.
The first path listed in
sourcepath is the location where EasyBuild will store downloaded source files,
organised by software name through subdirectories, so EasyBuild expects to have write permissions to this path.
For the other paths listed in
sourcepath only read permissions are required.
Make sure you have write permissions to the first path listed in
sourcepath, so EasyBuild is able
to store downloaded files there. Feel free to list additional paths if you already have a cache of downloaded
files available somewhere.
EasyBuild keeps track of the easyconfig files that were used for installations in the easyconfigs
archive, the location of which is specified by the
repositorypath configuration setting.
By default the specified path is assumed to be a regular directory, but using a Git repository as easyconfigs archive is also supported (for more details, see the EasyBuild documentation).
For the sake of this tutorial we recommend using a regular directory,
and sticking to the default location as a subdirectory of the
prefix configuration setting.
Modules tool & module syntax¶
Lmod as modules tool,
Lua as module syntax)
By default, EasyBuild assumes you are using Lmod as modules tool.
In addition, it will generate module files in Lua syntax, as supported by Lmod
To diverge from this, you can define the
modules-tool configuration setting to indicate you
are using a different modules tool; see the output of
eb --avail-modules-tools for a list of supported
Note that for anything other than Lmod, you must make
sure that the actual modules tool binary command is available through
$PATH (more information
on this in the EasyBuild documentation).
If you prefer that EasyBuild generates module files in Tcl syntax, you can instruct
it to do so via the
module-syntax configuration setting. Note that this is required if you are using
a modules tool other than Lmod, since only Lmod supports module files in
We recommend using EasyBuild with the defaults settings: Lmod as modules tool, and Lua as module syntax.
Robot search path¶
robot-paths specifies the location to the easyconfig files included with EasyBuild installation;
dependency resolution is not enabled)
When EasyBuild needs to locate one or more easyconfig files, it will do so via the robot search path.
This applies to both easyconfig files that were specified using only their filename as an argument to the
eb command, as well as to easyconfigs required to resolve dependencies (more on that later).
To control the robot search path, two configuration settings are available:
Both accept a colon-separated list of locations to consider when looking for easyconfig files,
The key difference between these two configuration settings is that defining
robot also enables dependency resolution,
and hence makes EasyBuild install missing dependencies, alongside
specifying a list of paths to consider when searching for easyconfig files.
On the other hand, defining
robot-paths does not have the side effect of enabling dependency resolution.
In addition, you can use the
--robot command line option without specifying any paths to it,
to only enable dependency resolution.
Keep in mind that when either of the
robot (with paths) or
robot-paths configuration settings are
defined, the default value corresponding to the location of easyconfigs included with the
EasyBuild is no longer considered.
There are ways around this however, which are outside of the scope of this tutorial.
For more information, see the EasyBuild documentation.
Module naming scheme¶
EasyBuild will use a specific naming scheme for the module files it generates for each of the software installations. This ensures consistency, regardless of who uses EasyBuild to perform the installation.
Different types of module naming schemes are supported (flat, hierarchical, ...) and you can provide an implementation of
your own custom module naming scheme if desired. A number of different naming schemes are included
with EasyBuild, which you can consult via
EasyBuildMNS module naming scheme roughly corresponds to the filename of easyconfig files,
and consists of the software name followed by a combination of the software version, toolchain and
an optional label (which corresponds to the value of the
versionsuffix easyconfig parameter):
<name>/<version><-toolchain><versionsuffix>. Just like with names of easyconfig
<-toolchain> part is omitted when the
system toolchain is used,
<versionsuffix> value is empty by default.
Configuring EasyBuild can be done in different ways:
- through one or more configuration files;
ebcommand line options;
Each of the methods corresponds to a configuration level.
Every configuration setting can be defined via one of these mechanisms, without exception!
Configuration level hierarchy¶
There is a strict hierarchy between the different configuration levels supported by EasyBuild.
Settings defined via a configuration file only override default values.
A configuration setting that is defined via the corresponding
$EASYBUILD_* environment variable
takes precedence over the value specified in a configuration file (if any).
Finally, values specified through
eb command line options always win,
regardless of whether the corresponding
configuration setting was already defined some other way, be it via a configuration file or
an environment variable.
For example, let us consider a fictional configuration setting named
- If a value for
magicis specified in an EasyBuild configuration file, then this value will only be used if the corresponding environment variable (
$EASYBUILD_MAGIC) is not defined and if the
--magiccommand line option is not used;
- If the
$EASYBUILD_MAGICenvironment variable is defined however, then its value will be used for the
- Unless the
--magiccommand line option is used, since in that case the value provided as an argument there will be used instead.
Configuration files are the most basic way of configuring EasyBuild.
Two types of are supported by EasyBuild: user-level and system-level
configuration files. The output of
eb --show-default-configfiles tells you which locations
are considered, and whether any configuration files were found.
EasyBuild configuration files are written in the standard INI format, and the configuration settings are grouped into different sections.
To create an EasyBuild configuration file, the output of
eb --confighelp is very useful:
it produces the list of all supported configuration settings which are readily grouped in sections
and with every entry commented out, along with accompanying descriptive comments mentioning the default values,
and in the correct syntax.
Configuration files are the recommended mechanism to define configuration settings that should always be in place, regardless of the software you are installing.
EasyBuild configuration files vs easyconfig files¶
EasyBuild configuration files are sometimes confused with easyconfig files, due to the similar name. However, these are two entirely different concepts!
EasyBuild configuration files (usually
*.cfg) are a way of configuring the general behaviour of EasyBuild
across different software installations. They define configuration settings,
such as the location where software should be installed, or the syntax that should
be used when generating module files.
An easyconfig file (
*.eb) on the other hand specifies the details for one particular software installation.
It does this by defining a set of easyconfig parameters, which tell EasyBuild the name and version
of the software to install, which toolchain and easyblock to use, etc.
For each software installation performed by EasyBuild, there is a corresponding easyconfig file. There typically are only a handful of configuration files used however, for example a system-level configuration file, perhaps combined with a user-level one. Or there may be no configuration files involved at all, since EasyBuild can also be configured through other mechanisms: environment variables and command line options.
$EASYBUILD_* environment variables¶
A particularly easy way to configure EasyBuild is through environment variables.
At startup, EasyBuild will pick up any environment variable of which the name starts with '
For each of these, it will determine the corresponding configuration setting (or exit with an error if
none was found).
Mapping the name of a configuration setting to the name of the corresponding environment variable is straightforward:
use capital letters, replace dashes (
-) with underscores (
_), and prefix with
For example: the
module-syntax configuration setting can be specified by defining
$EASYBUILD_MODULE_SYNTAX environment variable:
Configuring via environment variables is especially practical for controlling the EasyBuild configuration
in a more dynamic way. For example, you can implement a simple shell script that defines
environment variables based on the current context (user, hostname, other environment variables), and
configure EasyBuild through sourcing it.
Keep in mind that environment variables are only defined for the shell session you are currently working in.
If you want to configure EasyBuild through environment variables in a more persistent way,
you can leverage one of the shell startup scripts (for example
eb command line options¶
Finally, you can also configure EasyBuild by specifying one or more options to the
As mentioned earlier, the values for configuration settings defined this way override the value that is specified through any other means. So if you want to be sure that a particular configuration setting is defined the way you want it to be, you can use the corresponding command line option.
There are various configuration settings for which it only makes sense to use the command line option.
An example of this is letting the
eb command print the EasyBuild version (via
Although you could configure EasyBuild to always print its version and then exit whenever the
eb command is
run, that would not be very useful...
Command line options are typically used to define configuration settings that are only relevant to that particular EasyBuild session. One example is doing a test installation into a temporary directory:
eb --installpath /tmp/$USER example.eb
Inspecting the current configuration (
Given the large amount of available configuration settings in EasyBuild and the different configuration levels, you can easily lose track of exactly how EasyBuild is configured.
--show-config command line option you can
easily inspect the currently active EasyBuild configuration.
The output of
--show-config includes a sorted list of all configuration settings that are defined to a
along with a couple of important ones that are always shown (like
sourcepath, and so on).
In addition, it also indicates at which configuration level each setting was defined,
so you can trace down where it was defined if needed.
This is the output produced by
eb --show-config for the default EasyBuild configuration,
where EasyBuild was installed via
pip install --user (which affects the value shown for the
robot-paths configuration setting):
# # Current EasyBuild configuration # (C: command line argument, D: default value, E: environment variable, F: configuration file) # buildpath (D) = /home/example/.local/easybuild/build containerpath (D) = /home/example/.local/easybuild/containers installpath (D) = /home/example/.local/easybuild repositorypath (D) = /home/example/.local/easybuild/ebfiles_repo robot-paths (D) = /home/example/.local/easybuild/easyconfigs sourcepath (D) = /home/example/.local/easybuild/sources
As shown here, all configuration settings shown follow the default
prefix value (
and none of the values diverge from the default value, since all entries are marked with
(D) for "default value").
Now let us do some basic configuring and inspect the resulting output of
First, create a user-level EasyBuild configuration file to define the
prefix configuration setting:
mkdir -p $HOME/.config/easybuild echo '[config]' > $HOME/.config/easybuild/config.cfg echo 'prefix=/apps' >> $HOME/.config/easybuild/config.cfg
In addition, define the
buildpath configuration setting using the corresponding
eb --show-config while you specify that the
setting should be defined as
$ eb --show-config --installpath=/tmp/$USER # # Current EasyBuild configuration # (C: command line argument, D: default value, E: environment variable, F: configuration file) # buildpath (E) = /tmp/easybuild containerpath (F) = /apps/containers installpath (C) = /tmp/easybuild packagepath (F) = /apps/packages prefix (F) = /apps repositorypath (F) = /apps/ebfiles_repo robot-paths (D) = /home/example/.local/easybuild/easyconfigs sourcepath (F) = /apps/sources
The output indicates that the
installpath setting was specified through a command line option (indicated
(C)), that the
buildpath setting was defined via an environment
variable (indicated with
(E)), that the
robot-paths setting still has the default value (indicated with
(D)), and that all other configuration
settings were specified via a configuration file, some of which indirectly through the
prefix value (indicated with
Exercise C.1 - Configure EasyBuild
Configure EasyBuild to use the
easybuild subdirectory in your home directory for everything, except for:
- The location of the build directories: use
- The locations that should be considered when searching for source files:
/easybuild/sources, but make sure that source files that are downloaded by EasyBuild are stored in
Leave other configuration settings set to their default value.
(click to show solution)
This is pretty straightforward.
Here we just define the corresponding environment variables:
export EASYBUILD_PREFIX=$HOME/easybuild export EASYBUILD_BUILDPATH=/tmp/$USER export EASYBUILD_SOURCEPATH=$HOME/easybuild/sources:/easybuild/sources
The location where EasyBuild should download source files to
must be listed first in the
sourcepath configuration setting.
The output of
--show-config should look like this (assuming that
$USER is set to
buildpath (E) = /tmp/example containerpath (E) = /home/example/easybuild/containers installpath (E) = /home/example/easybuild packagepath (E) = /home/example/easybuild/packages prefix (E) = /home/example/easybuild repositorypath (E) = /home/example/easybuild/ebfiles_repo robot-paths (D) = /home/example/easybuild/software/EasyBuild/4.4.0/easybuild/easyconfigs sourcepath (E) = /home/example/easybuild/sources:/easybuild/sources
Exercise C.2 - Install a trivial software package with EasyBuild
Try running the following command:
Where do you expect to find the installation?
(click to show solution)
The software was installed in
since that's how we configured EasyBuild in Exercise 3.1:
$ ls $HOME/easybuild ebfiles_repo modules software sources
The actual installation is in
while the module file was generated in
$ ls $HOME/easybuild/software bzip2 EasyBuild $ ls $HOME/easybuild/software/bzip2 1.0.6 $ ls $HOME/easybuild/software/bzip2/1.0.6 bin easybuild include lib man
$ ls $HOME/easybuild/modules/all bzip2 EasyBuild $ ls $HOME/easybuild/modules/all/bzip2 1.0.6.lua
The source file for bzip2 1.0.6 was downloaded to
$ ls $HOME/easybuild/sources/b/bzip2 bzip2-1.0.6.tar.gz
We will discuss this in more detail in the next part of the tutorial.
Make sure EasyBuild is configured as instructed in exercise 3.1 before you continue with the rest of this tutorial.
next: Basic usage - (back to overview page)