SoftEnv Tutorial

SoftEnv is a program designed to make it easy to manage your environment variables. By adding a particular software package to your environment, SoftEnv automatically sets the appropriate PATH, CPATH, LD_LIBRARY_PATH, and MANPATH for the software you requested. This removes the confusion over which environment variables need to be changed and where the software is installed.

Listing Available Packages

To see a list of all available software, simply run the following command:

$ softenv

You’ll notice that SoftEnv differentiates between macros and keys. A macro is a collection of other macros and keys, and can be used to add common dependencies for a group of software packages. Macros can be identified by the @ sigil. A key is generally a single software package. Keys can be identified by the + sigil. Keys can be versioned, or they can be an alias to the most recent version. Keep in mind that the latest version can change, so if you want to stay up-to-date, use the unversioned key, or if you want to make sure your build remains stable, use a versioned key.

The softenv command has a number of useful options:

Searching for a particular package

$ softenv -k <string>

The -k option allows you to search for keys or macros with <string> in their name or description. This string is not case sensitive, and can be a regular expression, so if you want to search for NetCDF versions built with Intel 17, for example, you can run:

$ softenv -k "netcdf.*intel-17.0.0"

Adding Software to Your Environment

Now that you’ve found the software you need, how do you actually use it? There are a couple of different ways to do this.

Temporarily using software from the command line

Let’s say you only need to use CMake once to build your software, or you’re not sure if a particular soft key provides what you are looking for or not. You can add this package to your environment with the following command:

$ soft add +cmake

Now you can run the latest version of CMake to build your software. Once you are done with a particular soft key or want to try something different, you can remove it from your environment with the following command:

$ soft delete +cmake

Remember that software added to your environment from the command line is only temporary, and will no longer be available the next time you log in.

Permanently adding software upon login

To permanently configure your software environment, you can add soft keys and macros to a .soft file in your home directory. The default .soft file looks like:

# This is your SoftEnv configuration run control file.
#   It is used to tell SoftEnv how to customize your environment by
#   setting up variables such as PATH and MANPATH.  To learn more
#   about this file, do a "man softenv".

As you can see, the only macro enabled by default is @default. This macro contains a default compiler, a default MPI implementation, and OS paths like /usr/bin and /usr/lib. Whatever you do, DO NOT remove this macro. If you do, you will have to specify the full path for common programs like /usr/bin/vim.

Any soft keys and macros that you always want available can be added to this file. Note that order is important here. The first key you list will come first in your PATH, so make sure to always add new keys to the start of the file. That means if you have multiple versions of the same software in your .soft file, the first one is the one that is used.

Every time you log in, your .soft file will automatically be processed and the proper environment variables will be set. If you add new keys to your .soft file, they won’t appear until you either log out and log back in, or run the following command:

$ resoft

This command refreshes your software environment.

Custom Environment Variables

If you install your own software and want to add it to your environment, you can add custom environment variables to your .soft file. They should look something like:




For example, to add a program called myapp to your PATH, you could add:


to your .soft file. Environment variables can also be modified on a per-job basis by setting them in your job submission script.

Investigating a Particular Key or Macro

If you want to know where a particular software package is installed, or want to see exactly what a macro includes, you can use the following command to investigate it:

$ soft-dbq +cmake

This is particularly useful for macros:

$ soft-dbq @quantum-espresso-5.1.1

As you can see, this particular quantum espresso macro includes the Intel compiler and MVAPICH2 installations it was built with, along with a GUI for viewing the output. Try running soft-dbq on the @default macro if you want to see the default compiler and MPI it comes with.


For more information on SoftEnv, check out the official documentation. The following man pages are also available:

  • softenv-intro
  • softenv
  • soft
  • soft-dbq
  • resoft
SoftEnv Tutorial Sidebar