.\" Man page generated from reStructuredText
.\" by the Docutils 0.22.4 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "ENVML" "1" "2026-09-21" "5.7.0" "Modules"
.SH NAME
envml \- run a command in an environment setting up by Modules
.SH SYNOPSIS
.sp
\fBenvml\fP [\fIMODULE_ACTION\fP]... [\-\-] \fICOMMAND\fP [\fIARG\fP]...
.SH DESCRIPTION
.sp
The \fBenvml\fP command configures the environment using specified
Environment Modules actions and then given command.
.sp
This is useful for running a command in a modified environment without
permanently altering the current shell session.
.sp
\fBenvml\fP interprets its first arguments as module actions, then
switches to command execution after either encountering \fB\-\-\fP or determining
that the remaining arguments form the actual command to run.
.SH MODULE_ACTION FORMAT
.sp
Each module action argument can be one of the following forms:
.INDENT 0.0
.IP \(bu 2
\fBpurge\fP
Unload all currently loaded modulefiles.
.IP \(bu 2
\fBrestore[=coll]\fP
Restore the module environment from the named collection \fBcoll\fP\&. If no
name is given, restores the default collection.
.IP \(bu 2
\fBunload=mod1[&mod2...]\fP
Unload one or more specified modulefiles.
.IP \(bu 2
\fBswitch=mod1&mod2\fP
Unload \fBmod1\fP and load \fBmod2\fP\&.
.IP \(bu 2
\fB[load=]mod1[&mod2...]\fP
Load one or more specified modulefiles. \fBload=\fP can be omitted.
.UNINDENT
.sp
Multiple MODULE_ACTIONs can be passed in a single argument using the colon
(\fB:\fP) separator. The ampersand (\fB&\fP) is used to specify multiple modules
in a single action.
.SH COMMAND EXECUTION
.sp
Everything following the \fB\-\-\fP separator is treated as the command to execute
in the modified environment.
.sp
If no \fB\-\-\fP separator is provided, \fBenvml\fP assumes the first
argument is a MODULE_ACTION and the remaining arguments form the command to
execute.
.SH OPTIONS
.INDENT 0.0
.TP
.B \-\-help, \-h
Display usage information and exit.
.UNINDENT
.SH EXAMPLES
.sp
Restore default module collection then run \fBcommand arg1 arg2\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
envml restore command arg1 arg2
.EE
.UNINDENT
.UNINDENT
.sp
Purge all modules, then load \fBmod1\fP and \fBmod2\fP, and run the command:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
envml purge:mod1:mod2 command arg1 arg2
.EE
.UNINDENT
.UNINDENT
.sp
Use the \fB\-\-\fP separator to avoid ambiguity:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
envml restore load=mod1&mod2 \-\- command arg1 arg2
.EE
.UNINDENT
.UNINDENT
.SH EXIT STATUS
.sp
The \fBenvml\fP command returns the exit status of the executed command
or \fB1\fP if module action fails.
.SH DIAGNOSTICS
.sp
If the \fBmodule\fP command is not available in the shell (i.e., not a
shell function), \fBenvml\fP will print an error and exit.
.SH SEE ALSO
.sp
module \%<#\:module-1>, modulecmd \%<#\:modulecmd-1>, ml \%<#\:ml-1>, modulefile \%<#\:modulefile-5>
.SH Copyright
1996-2026, Modules Contributors
.\" End of generated man page.