Environment

    You can see the current environment variables using the env command:

    In Nushell, environment variables can be any value and have any type (see the column). The actual value of the env. variable used within Nushell is under the value column. You can query the value directly using the $env variable, for example, $env.PATH | length. The last raw column shows the actual value that will be sent to external applications (see for details).

    The environment is initially created from the Nu configuration file and from the environment that Nu is run inside of.

    There are several ways to set an environment variable:

    Using the let-env command is the most straightforward method

    1. > let-env FOO = 'BAR'

    ‘let-env’ is similar to the export command in bash.

    So if you want to extend the PATH variable for example, you could do that as follows.

    1. let-env PATH = ($env.PATH | prepend '/path/you/want/to/add')

    Here we’ve prepended our folder to the existing folders in the PATH, so it will have the highest priority. If you want to give it the lowest priority instead, you can use the append command.

    If you have more than one environment variable you’d like to set, you can use load-env to create a table of name/value pairs and load multiple variables at the same time:

    1. > load-env { "BOB": "FOO", "JAY": "BAR" }

    See for details.

    See Modules for details.

    Scoping

    When you set an environment variable, it will be available only in the current scope (the block you’re in and any block inside of it).

    Here is a small example to demonstrate the environment scoping:

    1. > let-env FOO = "BAR"
    2. > do {
    3.     $env.FOO == "BAZ"
    4. }
    5. true
    6. > $env.FOO == "BAR"
    7. true

    Common task in a shell is to change directory with the cd command. In Nushell, calling cd is equivalent to setting the PWD environment variable. Therefore, it follows the same rules as other environment variables (for example, scoping).

    Single-use environment variables

    A common shorthand to set an environment variable once is available, inspired by Bash and others:

    You can also use with-env to do the same thing more explicitly:

    1. > with-env { FOO: BAR } { echo $env.FOO }
    2. BAR

    The command will temporarily set the environment variable to the value given (here: the variable “FOO” is given the value “BAR”). Once this is done, the block will run with this new environment variable set.

    You can also set environment variables at startup so they are available for the duration of Nushell running. To do this, set an environment variable inside . For example:

    1. # In config.nu
    2. let-env FOO = 'BAR'

    Defining environment from custom commands

    1. > def-env foo [] {
    2.     let-env FOO = 'BAR'
    3. }
    5. > foo
    7. > $env.FOO
    8. BAR

    You can set the ENV_CONVERSIONS environment variable to convert other environment variables between a string and a value. For example, the includes conversion of PATH (and Path used on Windows) environment variables from a string to a list. After both env.nu and config.nu are loaded, any existing environment variable specified inside ENV_CONVERSIONS will be translated according to its from_string field into a value of any type. External tools require environment variables to be strings, therefore, any non-string environment variable needs to be converted first. The conversion of value -> string is set by the to_string field of ENV_CONVERSIONS and is done every time an external command is run.

    Let’s illustrate the conversions with an example. Put the following in your config.nu:

    1. let-env ENV_CONVERSIONS = {
    2.     FOO : {
    3.         from_string: { |s| $s | split row '-' }
    4.         to_string: { |v| $v | str collect '-' }
    5.     }
    6. }

    Now, within a Nushell instance:

    You can see the $env.FOO is now a list in a new Nushell instance with the updated config. You can also test the conversion manually by

    1. > do $env.ENV_CONVERSIONS.FOO.from_string 'a-b-c'

    Now, to test the conversion list -> string, run:

    1. > nu -c '$env.FOO'

    Because nu is an external program, Nushell translated the [ a b c ] list according to ENV_CONVERSIONS.FOO.to_string and passed it to the nu process. Running commands with nu -c does not load the config file, therefore the env conversion for FOO is missing and it is displayed as a plain string — this way we can verify the translation was successful. You can also run this step manually by do $env.ENV_CONVERSIONS.FOO.to_string [a b c]

    If we look back at the env command, the raw column shows the value translated by ENV_CONVERSIONS.<name>.to_string and the value column shows the value used in Nushell (the result of ENV_CONVERSIONS.<name>.from_string in the case of FOO). If the value is not a string and does not have to_string conversion, it is not passed to an external (see the raw column of PROMPT_COMMAND). One exception is PATH (Path on Windows): By default, it converts the string to a list on startup and from a list to a string when running externals if no manual conversions are specified.

    (Important! The environment conversion string -> value happens after the env.nu and config.nu are evaluated. All environment variables in env.nu and config.nu are still strings unless you set them manually to some other values.)

    Removing environment variables

    You can remove an environment variable only if it was set in the current scope via hide:

    1. > let-env FOO = 'BAR'
    2. ...
    3. > hide FOO
    1. > let-env FOO = 'BAR'
    2. > do {
    3.     hide FOO
    4.     # $env.FOO does not exist
    5.   }
    7. BAR

    You can check for more details about hiding.