Configuration

Nushell Configuration with env.nu and config.nu

Nushell uses a configuration system that loads and runs two Nushell script files at launch time:

  • env.nu is used to define environment variables or write files before config.nu starts. For example $env.NU_LIB_DIRS controls where Nu finds imports. Third party scripts, like prompts or miseopen in new window, must already be saved to disk before config.nu can read them.
  • config.nu is used to add definitions, aliases, and more to the global namespace. It can also use the environment variables and constants defined in env.nu. If you can't decide which file to add stuff, prefer config.nu.

Check where Nushell is reading these config files from by calling $nu.env-path and $nu.config-path.

> $nu.env-path
/Users/FirstNameLastName/Library/Application Support/nushell/env.nu

(You can think of the Nushell config loading sequence as executing two REPLopen in new window lines on startup: source /path/to/env.nu and source /path/to/config.nu. Therefore, using env.nu for environment and config.nu for other config is just a convention.)

When you launch Nushell without these files set up, Nushell will prompt you to download the default env.nuopen in new window and default config.nuopen in new window.

TIP

The default config files aren't required. If you prefer to start with an empty env.nu and config.nu then Nu applies identical defaults in internal Rust code. You can still browse the default files for default values of environment variables and a list of all configurable settings using the config commands:

> config env --default | nu-highlight | lines
> config nu --default | nu-highlight | lines

Control which directory Nushell reads config files from with the XDG_CONFIG_HOME environment variable. When you set it to an absolute path, Nushell will read config files from $"($env.XDG_CONFIG_HOME)/nushell".

WARNING

XDG_CONFIG_HOME must be set before starting Nushell. Do not set it in env.nu.

Here's an example for reading config files from ~/.config/nushell rather than the default directory for Windows, which is C:\Users\username\AppData\Roaming\nushell.

> $env.XDG_CONFIG_HOME = "C:\Users\username\.config"
> nu
> $nu.default-config-dir
C:\Users\username\.config\nushell

WARNING

XDG_CONFIG_HOMEopen in new window is not a Nushell-specific environment variable and should not be set to the directory that contains Nushell config files. It should be the directory above the nushell directory. If you set it to /Users/username/dotfiles/nushell, Nushell will look for config files in /Users/username/dotfiles/nushell/nushell instead. In this case, you would want to set it to /Users/username/dotfiles.

Configuring $env.config

Nushell's main settings are kept in the config environment variable as a record. This record can be created using:

$env.config = {
  ...
}

Note that setting any key overwrites its previous value. Likewise it's an error to reference any missing key. If $env.config already exists you can update or gracefully insert a cell-path at any depth using upsert:

$env.config = ($env.config | upsert <field name> <field value>)

By convention, this variable is defined in the config.nu file.

Environment

You can set environment variables for the duration of a Nushell session using the $env.<var> = <val> structure inside the env.nu file. For example:

$env.FOO = 'BAR'

(Although $env.config is an environment variable, it is still defined by convention inside config.nu.)

These are some important variables to look at for Nushell-specific settings:

  • LS_COLORS: Sets up colors per file type in ls
  • PROMPT_COMMAND: Code to execute for setting up the prompt (block or string)
  • PROMPT_COMMAND_RIGHT: Code to execute for setting up the right prompt (block)
  • PROMPT_INDICATOR = "〉": The indicator printed after the prompt (by default ">"-like Unicode symbol)
  • PROMPT_INDICATOR_VI_INSERT = ": "
  • PROMPT_INDICATOR_VI_NORMAL = "〉 "
  • PROMPT_MULTILINE_INDICATOR = "::: "

Configurations with built-in commands

The (config nu and config env) commands open their respective configurations for quick editing in your preferred text editor or IDE. Nu determines your editor from the following environment variables in order:

  1. $env.config.buffer_editor
  2. $env.EDITOR
  3. $env.VISUAL

Color Config section

You can learn more about setting up colors and theming in the associated chapter.

Remove Welcome Message

To remove the welcome message, you need to edit your config.nu by typing config nu in your terminal, then you go to the global configuration $env.config and set show_banner option to false, like this:

$env.config = {
  ...
  show_banner: false,
  ...
}

Configuring Nu as a login shell

To use Nu as a login shell, you'll need to configure the $env variable. This sets up the environment for external programs.

To get an idea of which environment variables are set up by your current login shell, start a new shell session, then run nu in that shell.

You can then configure some $env.<var> = <val> that setup the same environment variables in your nu login shell. Use this command to generate some $env.<var> = <val> for all the environment variables:

$env | reject config | transpose key val | each {|r| echo $"$env.($r.key) = '($r.val)'"} | str join (char nl)

This will print out $env.<var> = <val> lines, one for each environment variable along with its setting. You may not need all of them, for instance the PS1 variable is bash specific.

Next, on some distros you'll also need to ensure Nu is in the /etc/shells list:

> cat /etc/shells
# /etc/shells: valid login shells
/bin/sh
/bin/dash
/bin/bash
/bin/rbash
/usr/bin/screen
/usr/bin/fish
/home/jonathan/.cargo/bin/nu

With this, you should be able to chsh and set Nu to be your login shell. After a logout, on your next login you should be greeted with a shiny Nu prompt.

Configuration with login.nu

If Nushell is used as a login shell, you can use a specific configuration file which is only sourced in this case. Therefore a file with name login.nu has to be in the standard configuration directory.

The file login.nu is sourced after env.nu and config.nu, so that you can overwrite those configurations if you need. There is an environment variable $nu.loginshell-path containing the path to this file.

What about customizing iteractive shells, similar to .zshrc? By default config.nu is only loaded in interactive shells, not scripts.

macOS: Keeping /usr/bin/open as open

Some tools (e.g. Emacs) rely on an open command to open files on Mac. As Nushell has its own open command which has different semantics and shadows /usr/bin/open, these tools will error out when trying to use it. One way to work around this is to define a custom command for Nushell's open and create an alias for the system's open in your config.nu file like this:

alias nu-open = open
alias open = ^open

The ^ symbol escapes the Nushell open command, which invokes the operating system's open command. For more about escape and ^ see the chapter about escapes.

PATH configuration

In Nushell, the PATH environment variableopen in new window (Path on Windows) is a list of paths. To append a new path to it, you can use $env.<var> = <val> and append in env.nu:

$env.PATH = ($env.PATH | split row (char esep) | append '/some/path')

This will append /some/path to the end of PATH; you can also use prepend to add entries to the start of PATH.

Note the split row (char esep) step. We need to add it because in env.nu, the environment variables inherited from the host process are still strings. The conversion step of environment variables to Nushell values happens after reading the config files (see also the Environment section). After that, for example in the Nushell REPL when PATH/Path is a list , you can use append/prepend directly.

To add multiple paths only if not already listed, one can add to env.nu:

$env.PATH = $env.PATH | split row (char esep)
  | append /usr/local/bin
  | append ($env.CARGO_HOME | path join bin)
  | append ($env.HOME | path join .local bin)
  | uniq # filter so the paths are unique

This will add /usr/local/bin, the bin directory of CARGO_HOME, the .local/bin of HOME to PATH. It will also remove duplicates from PATH.

TIP

There's a convenience command for updating your system path but you must first open the std module (in preview):

use std *
path add /usr/local/bin ($env.CARGO_HOME | path join bin) # etc.

You can optionally --append paths to be checked last like the ones below.

Homebrew

Homebrewopen in new window is a popular package manager that often requires PATH configuration. To add it to your Nushell PATH:

# macOS ARM64 (Apple Silicon)
$env.PATH = ($env.PATH | split row (char esep) | prepend '/opt/homebrew/bin')

# Linux
$env.PATH = ($env.PATH | split row (char esep) | prepend '/home/linuxbrew/.linuxbrew/bin')

Pyenv

Pyenvopen in new window is a popular Python version manager. To add it to your Nushell PATH:

MacOS or Linux

# MacOS or Linux
$env.PATH = ($env.PATH | split row (char esep) | prepend $"(pyenv root)/shims")

Windows

Windows users need to install pyenv-winopen in new window and execute the Get-Command pyenv command in PowerShell to get the path of pyenv.ps1 after the installation.

The result usually looks like: C:\Users\<your-username>\.pyenv\pyenv-win\bin\pyenv.ps1

Then add the path of pyenv to your Nushell PATH:

# Windows
$env.Path = ($env.Path | split row (char esep) | prepend $"~/.pyenv/pyenv-win/bin/pyenv.ps1")
Contributors: Justin Ma, Reilly Wood, Darren Schroeder, Jakub Žádník, Adam Chalmers, Antoine Stevan, JT, Louis Salkeld, hedonihilist, Christopher Biscardi, Dan Davison, Dominique Martinet, Eduardo Canellas, Fernando Herrera, Gustavo Maia, Hofer-Julian, Hristo Filaretov, Ibraheem Ahmed, JT, Jack Deng, Jane Lusby, Jelle Besseling, Jeremiah, Joerg Schuetter, Jonathan Turner, Jordan Stewart, Kangaxx-0, Karthik Kumar Viswanathan, Levin Fritz, Martin Mauch, Mika Naylor, Máté FARKAS, Oscar Dominguez, Sertac Olgunsoylu, Sympatron GmbH, Texas Toland, Tyler Ruckinger, Yash Thakur, chtenb, jafriyie1, petrisch, prrao87, sec65, vent