MODULE(1)

NAME
module - command interface to the Modules package

SYNOPSIS
module [ sub-command ] [ sub-command-args ]

DESCRIPTION

module is a user interface to the Modules package. The Modules package provides for the dynamic modification of a user's environment via modulefiles.

Each modulefile contains the information needed to configure the shell for an application. Once the Modules package is initialized, the environment can be modified on a per-module basis using the module command which interprets modulefiles. Typically modulefiles instruct the module command to alter or set shell environment variables such as PATH, MANPATH, etc. modulefiles may be shared by many users on a system and users may have their own collection to supplement or replace the shared modulefiles.

The modulefiles are added to and removed from the current environment by the user. The environment changes contained in a modulefile can be summarized through the module command as well. If no arguments are given, a summary of the module usage and sub-commands are shown.

The action for the module command to take is described by the sub-command and its associated arguments.

  Package Initialization

The Modules package and the module command are initialized when a shell-specific initialization script is sourced into the shell. The script creates the module command as either an alias or function, creates Modules environment variables, and a snapshot of the environment is saved in ${HOME}/.modulesbeginenv. The module alias or function executes the modulecmd program located in ${MODULESHOME}/bin and has the shell evaluate the command's output. The first argument to modulecmd specifies the type of shell.

The initialization scripts are kept in ${MODULESHOME}/init/shellname where shellname is the name of the sourcing shell. For example, a C Shell user sources the ${MODULESHOME}/init/csh script. The sh, csh, tcsh, bash, ksh, and zsh shells are supported by modulecmd. In addition, an emacs "shell" is supported which writes the environment changes to stdout as emacs-readable lisp code.

  Module Sub-Commands

    help [modulefile...]
        Print the usage of each sub-command. If an argument is given, print the Module specific help information for the modulefile.

    load modulefile [modulefile...]
    add modulefile [modulefile...]
        Load modulefile into the shell environment.

    unload modulefile [modulefile...]
    rm modulefile [modulefile...]
        Remove modulefile from the shell environment.

    switch modulefile1 modulefile2
    swap modulefile1 modulefile2
        Switch loaded modulefile1 with modulefile2.

    display modulefile [modulefile...]
    show modulefile [modulefile...]
        Display information about a modulefile. The display sub-command will list the full path of the modulefile and all of the environment changes the modulefile will make if loaded.

    list
        List loaded modules.

    avail [path...]
        List all available modulefiles in the current MODULEPATH. All directories in the MODULEPATH are recursively searched for files containing the modulefile magic cookie. If an argument is given, then each directory in the MODULEPATH is searched for modulefiles whose pathname match the argument. Multiple versions of an application can be supported by creating a subdirectory for the application containing modulefiles for each version.

    use directory [directory...]
    use -append directory [directory...]
        Prepend directory to the MODULEPATH environment variable. The -append flag will append the directory to MODULEPATH.

    unuse directory [directory...]
        Remove directory from the MODULEPATH environment variable.

    update
        Attempt to reload all loaded modulefiles. The environment will be reconfigured to match the saved ${HOME}/.modulesbeginenv and the modulefiles will be reloaded. update will only change the environment variables that the modulefiles set.

    clear
        Force the Modules Package to believe that no modules are currently loaded.

    purge
        Unload all loaded modulefiles.

    initadd modulefile [modulefile...]
        Add modulefile to the shell's initialization file in the user's home directory. The startup files checked are .cshrc, .login, and .csh_variables for the C Shell; .profile for the Bourne and Korn Shells; .bashrc, .bash_env, and .bash_profile for the GNU Bourne Again Shell; .zshrc, .zshenv, and .zlogin for zsh. If a 'module load' line is found in any of these files, the modulefile are appended to any existing list of modulefiles. The 'module load' line must be located in at least one of the files listed above for any of the 'init' sub-commands to work properly. If the 'module load' line is found in multiple shell initialization files, all of the lines are changed.

    initrm modulefile [modulefile...]
        Remove modulefile from the shell's initialization files.

    initsw modulefile1 modulefile2
        Switch modulefile1 with modulefile2 in the shell's initialization files.

    initlist
        List all of the modulefiles loaded from the shell's initialization file.

    initclear
        Clear all of the modulefiles from the shell's initialization files.

  Modulefiles

modulefiles are written in the Tool Command Language (tcl) and are interpreted by modulecmd. modulefiles can use conditional statements. Thus the effect a modulefile will have on the environment may change depending upon the current state of the environment.

Environment variables are unset when unloading a modulefile. Thus, it is possible to load a modulefile and then unload it without having the environment variables return to their prior state.

ENVIRONMENT

MODULESHOME
    The location of the master Modules package file directory containing module command initialization scripts, the executable program modulecmd, and a directory containing a collection of master modulefiles.

MODULEPATH
    The path that the module command searches when looking for modulefiles. Typically, it is set to the master modulefiles directory, ${MODULESHOME}/modulefiles, by the initialization script. MODULEPATH can be set using 'module use' or by the module initialization script to search group or personal modulefile directories before or after the master modulefile directory.

LOADEDMODULES
    A colon separated list of all loaded modulefiles.

_LOADED_MODULEFILES_
    A colon separated list of the full pathname for all loaded modulefiles.

_MODULESBEGINENV_
    The filename of the file containing the initialization environment snapshot.

FILES

/depot/Modules
    The MODULESHOME directory.

${MODULESHOME}/modulefiles
    The directory for system-wide modulefiles. The location of the directory can be changed using the MODULEPATH environment variable as described above.

${MODULESHOME}/bin/modulecmd
    The modulefile interpreter that gets executed upon each invocation of module.

${MODULESHOME}/init/shellname
    The Modules package initialization file sourced into the user's environment.

${MODULEPATH}/.moduleavailcache
    File containing the cached list of all modulefiles for each directory in the MODULEPATH (only when the avail cache is enabled).

${MODULEPATH}/.moduleavailcachedir
    File containing the names and modification times for all sub-directories with an avail cache.

${HOME}/.modulesbeginenv
    A snapshot of the user's environment taken at Module initialization. This information is used by the module update sub-command.

SEE ALSO
modulefile(4)