eb-local builds and installs software with EasyBuild on top of EESSI 2026.06, into a directory you or your project own, and prints the shell lines that load EESSI and what you installed.
This page describes the static binary on this branch's main.
The 1.x Bash script, frozen until it is removed in 4.0.0, has a build, env, dev and clean only.
eb-local [OPTION]... <easyconfig> [eb options]
eb-local [OPTION]... --explain <easyconfig> [eb options]
eb-local eb [--] [eb options]
eb-local --explain eb [--] [eb options]
eb-local [OPTION]... env [--strict] [--json]
eb-local [OPTION]... dev [--strict] [--pure] [--json] [--buildenv MODULE] [--envrc] [--lock | --locked] [MODULE...]
eb-local rpath-wrappers [--for FAMILY | --unwrapped]
eb-local check [--recursive] [--quiet] [--json] FILE...
eb-local check (--module NAME/VERSION... | --dev | --prefix DIR) [--recursive] [--quiet] [--json]
eb-local [OPTION]... submit [--on NAME,...] [--print] <easyconfig> [eb options]
eb-local [OPTION]... list [--json | --missing] [NAME[/VERSION]...]
eb-local [OPTION]... doctor [--json] [--strict] [--workspace PATH] [--cvmfs] [--cvmfs-parallel N] [--mpi]
eb-local lmod-cache --modulepath DIR[:DIR] --cache-dir DIR --timestamp FILE [--spider CMD] [--verify]
eb-local lmod-cache --prefix DIR [--eessi-version VER] [--update-cmd CMD] [--dry-run]
eb-local modulerc --module-tree DIR [--default MODULE]...
[--alias NAME=MODULE]... [--hide MODULE]... [--dry-run | --check] [--json]
eb-local [OPTION]... clean [--logs-older-than DAYS] [--no-logs] [--sources] [--workspaces]
[--dry-run] [--delete] [--json]
eb-local [OPTION]... config [--check | --env | --get KEY] [--json]
eb-local [OPTION]... profiles [--json]
eb-local [OPTION]... uninstall NAME/VERSION... [--target TARGET] [--dry-run] [--delete] [--usage-log FILE]
eb-local [OPTION]... restore NAME/VERSION... [--dry-run]
eb-local site [list | show NAME | install NAME | check FILE] [--set KEY=VALUE]... [--to FILE] [--force]
eb-local overlay materialize --overlay FILE --base PATH [--out-dir DIR] [--dry-run | --check]
eb-local overlay bump [--eb-stack PATH] [--] [eb-stack package bump options...]
eb-local overlay plan [--eb-stack PATH] [--] [eb-stack package plan options...]
eb-local help | -h | --help | --version
OPTION is one of --profile NAME, --project DIR and --config FILE, which the options below describe.
eb-local --help prints:
eb-local: install and build software on top of EESSI 2026.06, into a
directory you own.
eb-local <easyconfig> [eb options] build and install with EasyBuild
eb-local --explain <easyconfig> [eb options]
the commands that build runs, as shell lines,
its checks as comments; creates and runs nothing
eb-local eb [--] [eb options] load EESSI-extend and run eb; no site file, no Slurm job.
At most one of EESSI_USER_INSTALL, EESSI_PROJECT_INSTALL,
EESSI_SITE_INSTALL, EESSI_CVMFS_INSTALL may be set, and a
present empty value counts as set; with none set, the
module uses $HOME/eessi and nothing is exported.
eb runs only if the module's install path is in the
tree that variable selects
eb-local --explain eb [--] [eb options]
the script eb runs, with its arguments; runs nothing
eb-local env [--strict] [--json] lines that make your installed modules visible;
--strict exits when the EESSI init file is missing
(also when EB_LOCAL_ENV_STRICT=1)
eb-local dev [--strict] [--pure] [--json] [--buildenv MODULE] [--envrc] [--lock | --locked] [MODULE...]
the same, plus MODULEs and a build environment,
so gcc, make, cmake and meson just work;
--strict exits when the EESSI init file is missing
(also when EB_LOCAL_ENV_STRICT=1);
--buildenv names the build environment to load;
--json prints the change as JSON, for env too;
--envrc writes that line to .envrc for direnv;
--pure purges loaded modules and LD_* first;
--lock records what loads in eb-local.lock,
--locked loads exactly that again
eb-local rpath-wrappers [--for FAMILY | --unwrapped]
lines that put RPATH wrappers for the compilers
on PATH first; dev uses them when no build
environment exists for the loaded compilers.
--unwrapped: only clang, clang++, flang,
flang-new and ld.lld, where no wrapper comes
first; dev adds them after a build environment
eb-local check [--recursive] [--quiet] [--json] FILE...
whether a program or library built here runs here:
its architecture, loader, run paths and libraries;
--recursive audits resolved DT_NEEDED libraries too
eb-local check (--module NAME/VERSION... | --dev | --prefix DIR) [--recursive] [--quiet] [--json]
the same for every ELF file in those installations,
the dev tree, or DIR; a file that is not ELF is skipped.
--quiet prints a file only when it has a problem
eb-local submit [--on NAME,...] [--print] <easyconfig> [eb options]
one batch job per node type the site file lists
in build.node_types, each building the recipe for
its CPU target; --print shows the jobs instead.
Deprecated, and removed in 4.0.0: --explain
prints an sbatch line for each node type
eb-local list [--json | --missing] [NAME[/VERSION]...]
what you installed, for which CPU targets, and
what this node's target lacks; --json prints one
line of JSON with schema_version 1; --missing
lists only modules missing on this node's target
eb-local doctor [--json] [--strict] [--workspace PATH] [--cvmfs] [--cvmfs-parallel N] [--mpi]
what in this shell, node or configuration would
stop a build or a module load; changes nothing;
--json prints one line of JSON with schema_version 1.
--strict exits 1 on warn lines as well as FAIL.
--workspace probes PATH without starting a build.
--cvmfs checks the CernVM-FS client.
--cvmfs-parallel N (1 to 8) reads repository
metadata from N tasks inside an allocation.
--mpi reports libfabric and UCX, and inside an
allocation runs a two-rank hello per approved transport
eb-local lmod-cache --modulepath DIR[:DIR] --cache-dir DIR
--timestamp FILE [--spider CMD] [--verify]
write Lmod's spiderT.lua for those module
directories, and a timestamp one second
older, so Lmod trusts the cache. A spider
that fails leaves both files unchanged.
--spider names the spider program;
default: spider. --verify compares
cached and uncached module inventories.
Does not read the site file
eb-local lmod-cache --prefix DIR [--eessi-version VER] [--update-cmd CMD]
[--dry-run]
for every CPU target under DIR, refresh
.lmod/cache with Lmod's cache updater
(like EESSI's update_lmod_caches.sh).
--dry-run lists targets; existing
--modulepath mode is unchanged
eb-local modulerc --module-tree DIR [--default MODULE]...
[--alias NAME=MODULE]... [--hide MODULE]... [--dry-run | --check] [--json]
write DIR/.modulerc.lua with the
defaults, aliases and hidden versions named;
preserve other lines. --dry-run prints the file;
--check reports drift and writes nothing;
--json prints one line of JSON with schema_version 1
eb-local clean [--logs-older-than DAYS] [--no-logs] [--sources] [--workspaces]
[--dry-run] [--delete] [--json]
remove what eb-local left behind; --no-logs
leaves the logs; --json prints one line of JSON
eb-local config [--check | --env | --get KEY] [--json]
the settings in force and where each came from;
--check also reads every secret (values not shown);
--env prints them as EB_LOCAL_* lines for export;
--get prints one resolved key's value (secret sources only);
--json is for the default output or --check, not --env or --get
eb-local profiles [--json] the profiles the configuration defines; --json
prints one line of JSON with schema_version 1
eb-local uninstall NAME/VERSION... [--target TARGET] [--dry-run] [--delete]
[--usage-log FILE]
remove an installation and its module file, for
every CPU target (or only TARGET), to the trash with
rtrash. --usage-log asks eb-keep-logs whether the
prefix is in FILE, and removes nothing when that exits 2
eb-local restore NAME/VERSION... [--dry-run]
bring them back from the trash, read-only again
eb-local site [list | show NAME | install NAME | check FILE] [--set KEY=VALUE]... [--to FILE] [--force]
a site file from a template built in, or from a
template file (a NAME with a slash); install
writes config.toml beside this program, mode 644;
site list takes --json for machine-readable output
eb-local overlay materialize --overlay FILE --base PATH [--out-dir DIR] [--dry-run | --check]
apply a digest-pinned overlay; writes a materialized
easyconfig and provenance.toml, or refuses when the
base digest changed; --dry-run validates and lists
the outputs without writing them; --check reports drift
and writes nothing
eb-local overlay bump [--eb-stack PATH] [--] [eb-stack package bump options...]
eb-local overlay plan [--eb-stack PATH] [--] [eb-stack package plan options...]
run eb-stack package bump or plan by subprocess only
eb-local help | --version
Every command but eb takes --profile NAME, --project DIR (a shared project
directory instead of $HOME/eessi) and --config FILE. Use env and dev with eval:
eval "$(eb-local env)"
eval "$(eb-local dev FFTW/3.3.10-GCC-15.2.0)"
Configuration: the site file (the first of config.toml beside this program,
/etc/eb-local/config.toml, eb-local.conf beside this program and
/etc/eb-local.conf), then ~/.config/eb-local/config.toml,
then EB_LOCAL_* variables (EB_LOCAL_SECRET_NAME=SOURCE for a secret),
then options. Builds use the allocation's own
node-local mount; a successful build removes its workspace unless
EB_LOCAL_KEEP_WORK=1. Secrets reach eb's environment only, and logs
written during a build are cleaned of them. A build gets every secret,
unless build.secrets or EB_LOCAL_BUILD_SECRETS names the ones it gets.
--config FILE, or EB_LOCAL_CONFIG=FILE without it, is read in place of the
site file when root or this program's owner owns it, otherwise in place of
your ~/.config/eb-local/config.toml when you own it; the other file is
still read, and only a site file may set the storage settings.
The first word names the command.
Without a command, the words go to eb in the order given, the easyconfig and eb's own options, and eb-local builds.
--profile, --project, --config, -h and --help are eb-local's wherever they come, and --explain is eb-local's before the first word that goes to eb.
After eb, every word goes to eb except -h and --help; after eb --, every word does, so eb-local eb -- --help prints eb's help.
--env as the first word is env, as in the 1.x script.
| Option | Meaning |
|---|---|
--profile NAME |
Use the profile NAME, in place of EB_LOCAL_PROFILE and default_profile. |
--project DIR |
Install into, and load from, the project directory DIR instead of the prefix, as the project setting does. |
--config FILE |
Read FILE in place of the site file when root or the owner of this program owns it; otherwise in place of ~/.config/eb-local/config.toml, when you own it. The other file is still read. |
--explain |
Before an easyconfig, or before eb: print what would run, and create and run nothing. |
-h, --help, help |
Print the usage on stdout and exit 0. |
--version |
Print the version line on stdout and exit 0. |
--json |
On list, check, doctor, modulerc, clean, config, profiles, and site list: print one line of JSON with schema_version 1 on stdout instead of the text report. Not with config --env or config --get. |
Each option that takes a value also takes it after an equals sign, as in --profile=gpu.
An empty value is refused either way, with OPTION needs a value.
eb refuses --profile, --project and --config, since it reads the install mode from the environment; site, check and rpath-wrappers take them and do not use them.
The version line names the program, its version, the target and optimize mode of the build, the Zig version, and the commit given to zig build as -Dcommit, or unknown.
Built with zig build --release=safe -Dcommit=0123abc, it prints:
eb-local 3.2.0 (x86_64-linux-musl, safe, zig 0.17.1, 0123abc)
Since v3.1.0, no CLI flag was removed or renamed.
The command line added --strict and --json on env, --json, --envrc, --pure, --lock and --locked on dev, --unwrapped on rpath-wrappers, --recursive on check, --cvmfs, --cvmfs-parallel and --mpi on doctor, lmod-cache (single-target and --prefix modes, with --verify), modulerc, overlay, site check, and --target and --usage-log on uninstall.
Build <easyconfig> with EasyBuild through EESSI-extend, for the CPU target of this node, and install it into the prefix, or into the project directory with --project.
A build runs only inside a Slurm job, in a workspace of its own in the job's node-local mount, <storage.node_local_root>/<storage.node_local_mount>.
Outside a job it builds nothing: it names the allocation the site suggests, and an sbatch line for each node type in build.node_types, and exits 2.
Its first line names the command that prints what it runs:
eb-local: what this runs: eb-local --explain pigz-2.8-GCCcore-15.2.0.eb --robot
A build that succeeds removes its workspace, unless EB_LOCAL_KEEP_WORK is 1, and ends with the line that makes what it installed visible:
eb-local: done. To use the modules in a new shell or job:
eval "$(eb-local env)"
A failed build keeps its workspace until the job ends.
A build exits with eb's status.
In a shell without a module command, a build, env and dev source the first Lmod init they can read: $LMOD_PKG/init/bash, or /usr/share/lmod/lmod/init/bash with LMOD_PKG unset, then /etc/profile.d/lmod.sh, then EESSI's own, the one eb-local eb sources; eb-local doctor names the one a build would source.
Stopped by a signal, it removes the secret values from the logs and then stops with the same signal.
Print the script a build runs, and create and run nothing, inside a Slurm job or outside one.
The output is, in order: comments that say where the build installs, the checks it makes first, and whether each secret reaches eb; the variables it sets for the script, with W standing for its workspace; a set -- line with the script's arguments; and the script itself.
With build.node_types in the site file, the comments also hold an sbatch line for each node type, which runs the same build as a batch job there.
The script does what you would type to use EESSI-extend by hand: clear the install variables a login shell may carry, set one of EESSI_USER_INSTALL or EESSI_PROJECT_INSTALL, load EESSI/2026.06, then EESSI-extend, which reads that variable as it loads, check that the install path EESSI-extend set is in <prefix>/versions, and run eb.
With W set to a workspace a build made, which holds build, cache, cargo, source-index and tmp, such as one a failed build kept or one kept with EB_LOCAL_KEEP_WORK=1, bash runs the printed text as a build runs its script; the checks before it and the cleaning of logs after it are eb-local's own.
Load EESSI and EESSI-extend in a bash with no profile and no rc file, and run eb with the arguments, with no site file and no Slurm job.
EESSI-extend takes the install mode from the install variables, of which at most one of EESSI_USER_INSTALL, EESSI_PROJECT_INSTALL, EESSI_SITE_INSTALL and EESSI_CVMFS_INSTALL may be set; a present, empty one counts.
With more than one set, eb runs nothing and the command exits 3.
| Variable | Mode | Prefix | Process umask |
|---|---|---|---|
EESSI_USER_INSTALL |
user | created when the value is not empty | 077 |
EESSI_PROJECT_INSTALL |
project | not created; its owner sets the group and the setgid bit | 002 |
EESSI_SITE_INSTALL |
site | the init's site software path | 022 |
EESSI_CVMFS_INSTALL |
cvmfs | the EESSI software path | 022 |
| none | user | $HOME/eessi, which need not exist before the module loads |
077 |
The module sets EASYBUILD_UMASK to the same end, with the sticky bit for a user prefix and the setgid bit for a project, and eb gets no --umask, so that value stands.
An argument of eb's still overrides it: --umask=022 is what a user-namespace build needs when Lmod, running as uid 0, skips a directory that others cannot search.
The module's help text says $HOME/EESSI; on EESSI 2026.06 it uses $HOME/eessi.
Before EESSI-extend loads, the script unsets host Rust and CMake wrappers, such as RUSTC_WRAPPER and CMAKE_C_COMPILER_LAUNCHER, and puts the compatibility layer's usr/bin, with its ld, first on PATH, even when rustc is not installed.
EasyBuild builds under $WORKING_DIR/easybuild; the module sets WORKING_DIR to /tmp/$USER when it is not set, and eb leaves it as you set it.
--profile, --project and --config are not options of eb, which stops with exit 2 when given one; the 1.x Bash script has no eb command.
Once EESSI-extend has loaded, the script exits 2 before eb runs when the install path the module set is outside the tree the install variable selects, or when EASYBUILD_INSTALLPATH_SOFTWARE or EASYBUILD_INSTALLPATH_MODULES is set.
Otherwise the command exits with eb's status.
With EB_LOCAL_EESSI_EXTEND set, not empty and not 0, every argument of eb-local goes to eb, as after eb-local eb --.
Print the script eb runs, after a set -- line with its arguments, and run nothing.
With more than one install variable set, it prints nothing on stdout and exits 3.
Print the shell lines that load EESSI and then EESSI-extend for the prefix, or the project directory, which puts the modules installed there on MODULEPATH.
Run them with eval "$(eb-local env)".
When stdout is a terminal, it also says on stderr that the lines change nothing until the shell runs them.
| Option | Meaning |
|---|---|
--strict |
Check that the EESSI init file exists in the emitted lines and exit 2 if absent (also when EB_LOCAL_ENV_STRICT=1). The exit is in the lines, so it ends the shell that evaluates them: meant for a job script, not an interactive shell. |
--json |
Print, in place of the lines, the change they make to the environment, as one line of JSON. |
With --json, eb-local runs the lines in a bash child and prints how that shell's environment then differs from the caller's: {"schema_version":1,"kind":"env","set":[{"name":...,"value":...}],"unset":[...]}, both lists sorted by name. A shell that cannot evaluate POSIX lines applies it; in nushell:
def --env --wrapped eb [...args] {
let change = (^eb-local ...$args --json | from json)
$change.set | reduce --fold {} {|var, acc| $acc | upsert $var.name $var.value } | load-env
hide-env --ignore-errors ...$change.unset
}
eb env
eb dev FFTW/3.3.10-GCC-15.2.0
Only variables are in the change. Shell functions and aliases, such as Lmod's module, stay in the bash child, so a later module load in the other shell is not possible this way; name the modules on the dev line. What the lines print goes to stderr. If the lines fail in bash, nothing is printed and the status is 1.
Print the lines env prints, then the lines that load the modules dev.modules names and those named on the line, then a build environment, and that set EB_LOCAL_DEV_PREFIX to <prefix>/dev/<EESSI version>/<CPU target>, with the GPU target appended when EESSI found one.
| Option | Meaning |
|---|---|
--strict |
Check that the EESSI init file exists in the emitted lines and exit 2 if absent (also when EB_LOCAL_ENV_STRICT=1). As for env, the exit ends the shell that evaluates the lines. |
--json |
Print the change the lines make to the environment as one line of JSON, as env --json does, with kind dev. |
--buildenv MODULE |
Load MODULE as the build environment whatever the compilers, as dev.buildenv does. |
--envrc |
Write the line that evaluates this dev to .envrc in the working directory, for direnv, and print nothing on stdout. |
dev --envrc MODULE... writes three lines to .envrc:
# >>> eb-local dev >>> rerun `eb-local dev --envrc` to change these lines
eval "$(/path/to/eb-local dev MODULE...)"
# <<< eb-local dev <<<The program is named by its own path, and --config, --profile, --project and --buildenv are repeated on the line. A block already in the file is replaced and every other line is kept; a file without one gets it appended. A begin line without its end line is refused. Run direnv allow once per change. direnv evaluates the file in bash and gives the calling shell the change, so the environment follows the directory in bash, zsh, fish, nushell and the other shells direnv has a hook for, and is taken back on leaving it. As with --json, only variables reach the calling shell.
--pure |
Before anything loads, run module purge and unset LD_LIBRARY_PATH, LD_PRELOAD and LD_AUDIT. |
|---|---|
--lock |
Run the lines in a bash child and write what loaded to eb-local.lock in the working directory; print nothing on stdout. |
--locked |
Print the lines that load exactly the modules of eb-local.lock, from a purged shell. Takes no MODULE. |
dev --lock MODULE... records what a dev environment resolved to: stack.module, the EESSI version, the CPU target (EESSI_SOFTWARE_SUBDIR), the accelerator target, and every loaded module with its version, in load order, the build environment among them. The file is one line of JSON with kind dev-lock. It is not written when the lines load no module.
dev --locked loads that list and nothing else: it purges first, as --pure does, and names every module in full, so Lmod resolves nothing. A lock written with another stack.module is refused. When the shell's CPU target is not the lock's, the lines say so and load none of its modules; node types with the same CPU target share their binaries, so a lock from one loads on the other. --json and --envrc work with --locked: dev --envrc --locked writes the locked line to .envrc.
Without --pure, the modules the shell already has stay loaded beside the ones dev names, and the loader variables stay as they are, with a warning for LD_LIBRARY_PATH. With it, the build environment is the stack, the named modules and the build environment only. Sticky modules survive module purge. A site that preloads a library for every process (XALT through LD_PRELOAD) loses that in this shell.
A MODULE starts with a letter or digit and holds letters, digits, ., _, +, - and single slashes, with none at the end.
With LD_LIBRARY_PATH set in the shell, dev warns on stderr.
Write RPATH wrappers for the compilers and linkers on PATH into a directory below $XDG_CACHE_HOME/eb-local, or $HOME/.cache/eb-local without it, and print the lines that put that directory first on PATH and name it in EB_LOCAL_RPATH_WRAPPERS.
The names it wraps are gcc, g++, c++, cc, gfortran, clang, clang++, flang, flang-new, icx, icpx, ifx, nvc, nvc++, nvfortran, ld, ld.bfd, ld.gold and ld.lld.
| Option | Meaning |
|---|---|
--for FAMILY |
Say on stderr that no build environment for the FAMILY compilers is available, as dev does. |
--unwrapped |
Wrap only the clang, clang++, flang, flang-new and ld.lld on PATH that no other wrapper comes before, and print nothing when there are none. |
Without --unwrapped, finding nothing to wrap is exit 1.
For each FILE, print its machine, its program interpreter (the loader), its RPATH or RUNPATH, and where each library it needs resolves, ignoring LD_LIBRARY_PATH, then one line for all of them:
eb-local check: no problems
A problem is a line of its own, after problem:, below the line it concerns:
| Problem | When |
|---|---|
built for MACHINE; this node is MACHINE |
The file is for another architecture. |
the loader is the host's, not the compatibility layer's under DIR |
EESSI is loaded, and the file names a loader outside its compatibility layer. |
RUNPATH, which LD_LIBRARY_PATH overrides and the libraries' own dependencies ignore; link with --disable-new-dtags for RPATH |
The file records RUNPATH rather than RPATH. |
run paths into the TARGET software tree; this shell is TARGET: build it again on this node type |
A run path, or a directory in LD_LIBRARY_PATH, leads into the tree of a CPU target other than $EESSI_SOFTWARE_SUBDIR. |
LIBRARY does not exist |
The file names a library by its path, and there is none. |
LIBRARY is not found |
No run path, no directory in LD_LIBRARY_PATH and none of the loader's directories holds the library. |
LIBRARY is found only through LD_LIBRARY_PATH |
The same, but a directory in LD_LIBRARY_PATH holds it. |
LIBRARY comes from the host, not from EESSI |
EESSI is loaded, and the library resolves outside it. |
By default, check follows only the libraries the file names directly; --recursive follows resolved DT_NEEDED shared libraries transitively and audits each unique resolved library once.
--module NAME/VERSION, --dev and --prefix DIR audit every ELF file in place of the files named on the line.
A file that is not ELF is skipped, and a symbolic link is not followed, so a link cannot point the audit outside the tree.
--module may be repeated, and further NAME/VERSION words after it name more modules.
Each must be installed. Every CPU target's installation is audited, and the module files are not: they are not ELF.
--dev reads EB_LOCAL_DEV_PREFIX when it is set, and otherwise <prefix>/dev/$EESSI_VERSION/$EESSI_SOFTWARE_SUBDIR, with $EESSI_ACCELERATOR_TARGET appended when that is set.
--prefix is any directory and does not read the site file.
The three are alternatives to naming files, and to each other.
--quiet prints a file only when it has a problem, and still ends with the summary line.
With no ELF file in the tree, and without --quiet, check says eb-local check: no ELF files and then eb-local check: no problems.
--json prints one line of JSON with schema_version 1, kind check, problem_count, unreadable, elf_count, and a files array of path, machine and problems.
The shape is in check.schema.json.
It exits 0 when there are no problems, 1 when there are, and 2 when a named file cannot be read or is not ELF, or when a file in a tree cannot be read.
A file that is not ELF is not a failure of a tree audit.
With --json, these codes are unchanged; only the summary on stdout is JSON.
Send one batch job for each node type in build.node_types, each running this eb-local with the same easyconfig, options and configuration.
submit is deprecated, and is removed in 4.0.0; --explain prints the same jobs as sbatch lines.
| Option | Meaning |
|---|---|
--on NAME,... |
Only the node types named. |
--print |
Print the jobs, and submit nothing. |
--on and --print come before the easyconfig; the words after it go to eb.
It exits 1 when sbatch refuses a job, and 2 when the site file has no build.node_types.
Print each module installed in the prefix, or the project directory, with a column for each CPU target it has a tree for, x where the module is built for that target and - where it is not.
With EESSI loaded, the column of this node's target is marked *, and the modules it lacks are named.
A NAME keeps the modules of that name, and a NAME/VERSION that module.
--missing prints only the sorted NAME/VERSION lines missing on the loaded CPU target, or nothing when every matching module is built there, and exits 2 when EESSI is not loaded.
--missing and --json cannot be used together.
--json prints one line of JSON with schema_version 1, kind list, the prefix, filters, empty, CPU targets, modules with a built boolean per target, missing_on_node, and nullable node_target and hint.
The shape is in list.schema.json.
Print one line for each check of what would stop a build, eb-local eb or a module load, each starting ok, info, warn or FAIL, then a line that says whether anything stops a build.
It checks the site file, the secrets a build reads (never their values), the prefix and its permissions, install variables and LD_LIBRARY_PATH left in the shell, the EESSI init eb-local eb sources, the allocation's node-local mount, whether EESSI is loaded and your modules are on MODULEPATH, the Lmod init a build sources where the shell has no module command, eessi-arch-guard, and rtrash.
With --workspace PATH, it also creates, writes, renames, executes and removes a small probe in that existing directory.
It reports the file-system type, whether the storage is node-local or shared, free bytes and inodes, a noexec mount, and whether the effective XDG_CACHE_HOME (or $HOME/.cache when unset) is inside the workspace.
The check does not create a build workspace and never starts a build.
It names an entry of PERL5LIB, PYTHONPATH, R_LIBS*, CMAKE_PREFIX_PATH or PKG_CONFIG_PATH, and a compiler-wrapper variable (CC, CXX, FC, F77, F90, F95, CPP, the OMPI_, MPICH_ and I_MPI_ forms, RUSTC_WRAPPER, CCACHE_*, SCCACHE_* and CMAKE_*_COMPILER_LAUNCHER), that resolves outside the approved prefixes.
A build keeps that entry unless build.clear_foreign_prefixes is set.
It reports the path /etc/localtime resolves to, warns when that file is its own bind mount, and warns about a host library directory a container runtime injected, including /.singularity.d/libs and a directory named by APPTAINER_CONTAINLIBS or SINGULARITY_CONTAINLIBS.
With --cvmfs, it also checks the CernVM-FS repository named by EESSI_CVMFS_REPO, or /cvmfs/software.eessi.io.
It reports whether that mount is present, a stale FUSE mount, or returning an input/output error.
It reports the HTTP proxy in force: CVMFS_HTTP_PROXY in the environment wins over /etc/cvmfs/default.conf, default.local, domain.d and config.d, and a value taken from the environment is named as one a host can inject.
DIRECT is direct mode.
When cvmfs_config is on PATH, it runs cvmfs_config probe and cvmfs_config chksetup; a stale mount skips the probe.
--cvmfs-parallel N, or doctor.cvmfs_parallel when the flag is omitted, reads repository metadata from N tasks, and only inside an allocation.
It uses srun -n N stat when srun is on PATH, and otherwise reads from N processes of its own.
A build does not run these checks and does not set a CernVM-FS variable.
With --mpi, it reports whether fi_info and ucx_info are on PATH, and any Slurm CPU or memory bind in SLURM_CPU_BIND, SLURM_CPU_BIND_LIST and SLURM_MEM_BIND.
Inside an allocation it compiles a two-rank hello with mpicc and runs it with mpirun -np 2 for each transport in doctor.mpi_transports.
The hello for ofi is run with OMPI_MCA_pml set to cm and OMPI_MCA_mtl set to ofi.
The hello for ucx is run with OMPI_MCA_pml set to ucx and OMPI_MCA_mtl set to ^ofi.
Those variables are set only on that hello. A build does not set them, and it does not set FI_PROVIDER.
Outside an allocation the hello is not compiled.
Where the shell has a module command, a build keeps it and its MODULEPATH, so doctor checks that a directory on MODULEPATH holds stack.module.
Inside a job with EESSI loaded, it asks eessi-arch-guard, where that is on PATH, as a build asks it, and shows the target it selects; a guard that cannot select one is a warn, since a build's own run of it decides.
With a site file, what stops a build is a FAIL, and what stops only eb-local eb is a warn; without one, builds cannot run, so what stops eb-local eb is the FAIL.
It changes nothing, and exits 1 when a line says FAIL.
| Option | Meaning |
|---|---|
--json |
Print one JSON document instead of human-readable lines. |
--strict |
Exit 1 whenever a warn line appears as well as FAIL, setting failed to true in --json. |
--workspace PATH |
Probe the existing absolute directory PATH and report its storage and cache isolation. |
--cvmfs |
Check the CernVM-FS client. Off unless this flag, or --cvmfs-parallel, is given. |
--cvmfs-parallel N |
Also read repository metadata from N tasks, 1 to 8, inside an allocation. Implies --cvmfs. |
--mpi |
Report libfabric, UCX and Slurm binding, and run a two-rank hello per site-approved transport inside an allocation. Off unless this flag is given. |
--json prints one line of JSON with schema_version 1, kind doctor, site_file, failed, lines (level and text), and summary.
The shape is in doctor.schema.json.
With --json, exit 1 still means failed is true (a FAIL line, or a warn line under --strict); scripts read failed in the document.
Write spiderT.lua in --cache-dir from Lmod's spider -o spiderT, for every directory in --modulepath, then set --timestamp one second older than that file.
Lmod treats a newer timestamp as a stale cache and does not show the modules the cache names.
A spider that cannot start, exits non-zero, or writes nothing leaves the cache and the timestamp as they were.
With --verify, the command first writes the candidate to a temporary directory inside --cache-dir.
It points a temporary LMOD_RC at the candidate and compares normalized output from module --terse avail with and without LMOD_IGNORE_CACHE=yes.
It atomically replaces spiderT.lua only when both inventories parse and match.
An inventory mismatch or parsing failure leaves the previous cache and timestamp unchanged.
With --prefix, the command walks every CPU target under the prefix (versions/*/software/… or software/…), prepends each accelerator's modules/all directory on that CPU (as EESSI's filesystem-layer update_lmod_caches.sh does), and runs Lmod's update_lmod_system_cache_files into <cpu>/.lmod/cache.
--dry-run lists each target, cache directory and colon-separated MODULEPATH; it changes no file.
It does not read the site file. --profile, --project and --config are accepted and ignored.
| Option | Meaning |
|---|---|
--modulepath DIR[:DIR] |
The module directories, separated by colons. Absolute. Required without --prefix. |
--cache-dir DIR |
The directory that receives spiderT.lua. Absolute. Required without --prefix. Created if it is missing. |
--timestamp FILE |
The timestamp file Lmod compares with the cache. Absolute. Required without --prefix. |
--spider CMD |
The spider program for single-target mode. Default: spider on PATH. |
--verify |
In single-target mode, compare the candidate cache inventory with uncached module discovery before replacing the cache. |
--prefix DIR |
Walk DIR for CPU targets and refresh each .lmod/cache with Lmod's cache updater. Absolute. |
--eessi-version VER |
With --prefix, only DIR/versions/VER/software; default is every versions/*/software. |
--update-cmd CMD |
Lmod's update_lmod_system_cache_files program. Default: DIR/compat/linux/$(uname -m)/usr/share/Lmod/libexec/update_lmod_system_cache_files. |
--dry-run |
With --prefix, list targets only. |
Exit 0 means both files were written or every prefix target was updated. Exit 2 is a missing, relative, or conflicting option. Exit 127 means spider, the cache updater, or module with --verify could not be started. With --verify, any inventory parsing or comparison failure exits 1; otherwise any other exit is spider's or the cache updater's, and caches are left as they were on failure.
Write or update .modulerc.lua at the root of --module-tree.
The command adds only the defaults, aliases and hidden versions named explicitly; it never examines the tree to select a default.
Existing lines are preserved, and a line already present is not duplicated.
| Option | Meaning |
|---|---|
--module-tree DIR |
The absolute module tree containing .modulerc.lua. Required. |
--default MODULE |
Add module_version("MODULE", "default"). Repeatable. |
--alias NAME=MODULE |
Add module_alias("NAME", "MODULE"). Repeatable. |
--hide MODULE |
Add hide_version("MODULE"). Repeatable. |
--dry-run |
Print the complete resulting file and leave the tree unchanged. |
--check |
Print whether the requested directives would update the file, write nothing, and exit 1 when they would. |
--json |
Print one JSON document with schema_version 1 instead of text; see modulerc.schema.json. |
At least one directive option is required.
--dry-run and --check cannot be used together.
--json works with write, --dry-run (including content in the JSON) and --check (keeping exit 1 on drift).
Any invalid UTF-8 byte in a path, directive, or content is replaced with the Unicode replacement character U+FFFD, so non-UTF-8 paths or contents do not round-trip.
Running the same command again produces identical file contents.
This command does not read the site file; --profile, --project and --config are accepted and ignored.
Keep site recipe changes in a digest-pinned overlay file instead of copying an upstream easyconfig.
materialize applies [replace], [patches], and [dependencies.add] / [dependencies.replace] tables, refuses when base_digest no longer matches the base file, and writes materialized-<name> plus provenance.toml.
| Subcommand | Meaning |
|---|---|
materialize |
Read --overlay FILE and --base PATH; write outputs under --out-dir (default: beside the overlay). --dry-run validates the inputs and lists both output paths without creating them. --check compares the materialized recipe and provenance against disk without writing, exiting 0 when up to date and 1 when either would update. Exit 2 when the base digest drifted or both --dry-run and --check are given. |
bump |
Run eb-stack package bump with every argument after -- (including --help, --config, --profile, and --project); --eb-stack PATH names the program when it is not on PATH. |
plan |
Run eb-stack package plan the same way. |
The overlay format is documented in Recipe overlay file. These commands do not read the site file.
Remove what eb-local left in the prefix, or the project directory: by default the build logs in .eb-local/logs older than clean.logs_older_than_days.
| Option | Meaning |
|---|---|
--logs-older-than DAYS |
The logs more than DAYS whole days old, in place of clean.logs_older_than_days; DAYS is at most 99999. |
--no-logs |
No logs. |
--sources |
The downloaded source archives in .eb-local/sources too. |
--workspaces |
Your build workspaces in the job's node-local mount too; only inside the Slurm job that made them. |
--dry-run |
Print what would be removed, and remove nothing. |
--delete |
Delete for good when clean.trash does not move files to the trash. |
--json |
Print one JSON document with schema_version 1 instead of text. |
Files go to the trash with rtrash as clean.trash says; workspaces are deleted.
A directory among the logs, such as the reprod_* copies of a failed build's easyconfig, easyblocks and hooks, goes whole once neither it nor anything in it is newer than the cutoff: the copies keep their originals' older times, and a file added to a directory makes the directory new.
clean never follows a symbolic link out of the installation directory.
With clean.trash none, or auto and no rtrash on PATH, it removes nothing without --delete, and exits 1.
If any item or build workspace cannot be removed, clean warns and exits 1 (including with --json, where removed_items and removed_workspaces report the actual counts).
With --json, stdout holds one line of JSON with schema_version 1, kind clean, prefix, dry_run, action (nothing, dry-run, trashed, deleted, workspaces-only or refused), items (path and kind), workspaces, removed_items and removed_workspaces; see clean.schema.json.
Any invalid UTF-8 byte in a path is replaced with the Unicode replacement character U+FFFD, so non-UTF-8 paths do not round-trip.
Print every setting in force, with where its value came from: default, a file and line with its layer and profile, a variable, or an option.
The configuration files lists the settings.
| Option | Meaning |
|---|---|
--check |
Also read each secret, and print ok, or FAILED: and why, where the file that set it would be; never the value. |
--env |
Print the settings as export EB_LOCAL_... lines for a shell, with each secret's source and never its value. |
--get KEY |
Print the resolved value of KEY (one item per line for list keys; secret sources only), exiting 1 when unset or empty and 2 when KEY is unknown. |
--json |
Print one line of JSON instead of the table; with --check, secret rows include status (listed, ok, or failed with optional detail). Not with --env or --get. |
It exits 1 with --check when a secret cannot be read or the project directory cannot be used.
With --json, the same holds; the document has check_failed true.
--json without --check prints schema_version 1, kind config, profile, check (false), check_failed (false), settings, and secrets listed only (with detail set to null).
With --check, check is true and each secret row records whether it could be read.
The shape is in config.schema.json.
Print each profile the configuration files define, with the layer and the file that define it, or no profiles are defined.
--json prints schema_version 1, kind profiles, and a profiles array of name, layer and path.
The shape is in profiles.schema.json.
Remove each installation NAME/VERSION names, for every CPU target, with its module files and the links EasyBuild makes to them from modules/CLASS/, and print what it removes.
EasyBuild leaves an installation read-only; uninstall makes its directories writable first.
| Option | Meaning |
|---|---|
--target TARGET |
Remove and check dependents only in the CPU tree matching TARGET (a full target such as x86_64/amd/zen4, or a short name when unique; an ambiguous short name exits 2 and lists the candidate trees). |
--dry-run |
Print what would be removed, and remove nothing. |
--delete |
Delete for good when clean.trash does not move files to the trash. |
--usage-log FILE |
Ask eb-keep-logs whether the install prefix is named in FILE, and remove nothing when that command exits 2. |
It removes nothing, and exits 2, when another module installed in the prefix loads one named and is not named too.
With clean.trash none, or auto and no rtrash on PATH, it removes nothing without --delete, and exits 1.
--usage-log FILE runs eb-keep-logs used --prefix PREFIX --require-none FILE after that dependents check and before anything is listed or removed.
PREFIX is the install prefix.
eb-local does not read FILE.
When that command exits 0, uninstall goes on as it would without the option, including a dry run.
When it exits 2, or any other status, or eb-keep-logs is not on PATH or cannot be run, uninstall removes nothing, exits 2, and prints what eb-keep-logs wrote.
Without --usage-log, uninstall does not run eb-keep-logs.
restore does not take the option, and uninstall takes it once.
Bring each NAME/VERSION that uninstall moved to the trash back, for every CPU target, with rtrash restore, and make it read-only again.
| Option | Meaning |
|---|---|
--dry-run |
Print what would come back, and restore nothing. |
One that is not in the trash for the prefix is exit 2, and so is a path in the trash more than once, as after two uninstall runs: it restores nothing, and names the rtrash restore command for that path.
rtrash restore on one path brings back read-only files in writable directories: rtrash moves a directory, and empties the trash, only when its directories are writable.
Print or write a site file from a template: slurm, built in, or a template file of the site's own, named with a slash.
| Word or option | Meaning |
|---|---|
list |
Print each built-in template and its placeholders; site alone does the same. --json prints one line of JSON; see site_list.schema.json. |
show NAME |
Print the site file the template NAME makes. |
install NAME |
Write that site file to config.toml beside this program, mode 644. |
check FILE |
Validate an existing site file as a site configuration layer without installing it. |
--set KEY=VALUE |
Fill the placeholder KEY; may be given more than once. |
--to FILE |
With install: write FILE instead. |
--force |
With install: replace a file that exists. |
show and install check that the file loads as a site file first.
A value with a quote, a backslash or a control character is refused.
| Status | Meaning |
|---|---|
| 0 | Done, or nothing to do. |
| 1 | check found a problem; doctor printed a FAIL; config --check could not read a secret or use the project directory; lmod-cache --verify failed or lmod-cache --prefix found no target; modulerc --check would update the file; overlay materialize --check would update the outputs; clean or uninstall had something to remove and no way to, or clean failed to remove some items or build workspaces; rpath-wrappers found nothing to wrap; submit: sbatch refused a job. |
| 2 | Refused, with the reason on stderr after eb-local:, or the command line was wrong; a build outside a Slurm job; check could not read a file. |
| 3 | eb or --explain eb: more than one install variable is set. |
| N | A build or eb: eb exited N. |
Commands that take --json use the same exit codes as their text output.
Refusals and usage errors still print on stderr; only the report on stdout becomes one JSON line.
Any invalid UTF-8 byte in a path or string field is replaced with U+FFFD, so non-UTF-8 strings do not round-trip.
With --json, check still exits 1 for problems and 2 when a file cannot be read; doctor still exits 1 when failed is true in the document; config --check --json still exits 1 when check_failed is true.
The Bash script eb-local, 1.x, is frozen: it gains no commands, and it is removed in 4.0.0, when the test suite's default run against it ends too.
It needs GNU coreutils, util-linux findmnt, Lmod and an EESSI 2026.06 mount, and has no profiles or secrets.
It reads one site file, eb-local.conf: the file EB_LOCAL_CONFIG names, else the one beside the script, else /etc/eb-local.conf, used only when it is a regular file, not a symbolic link, not writable by group or others, and owned by root, the script's owner or you.
Its key = value lines are the 1.x keys The configuration files lists.
- The configuration files, for each setting.
- Refusals, for what each refusal means.
- Give a secret only to the builds that need it.
- Where EESSI-extend installs.
- The API, for the code of each component.