Configuration

Quickstart

While Nushell provides many options for managing its startup and configuration, new users can get started with just a few simple steps:

1. Tell Nushell what editor to use:

   $env.config.buffer_editor = <path_to_your_preferred_editor>

   For example:

   $env.config.buffer_editor = "code"
   # or
   $env.config.buffer_editor = "nano"
   # or
   $env.config.buffer_editor = "hx"
   # or
   $env.config.buffer_editor = "vi"
   # with args
   $env.config.buffer_editor = ["emacsclient", "-s", "light", "-t"]
   # etc.

2. Edit config.nu using:

   config nu

   This will open the current config.nu in the editor defined above.

3. Add commands to this file that should run each time Nushell starts. A good first example might be the buffer_editor setting above.

   You can find a detailed list of available settings using:

    config nu --doc | nu-highlight | less -R

4. Save, exit the editor, and start a new Nushell session to load these settings.

That's it! More details are below when you need them ...

config nu --doc | nu-highlight | less -R

Configuration Overview

Nushell uses multiple, optional configuration files. These files are loaded in the following order:

1. The first file loaded is env.nu, which was historically used to override environment variables. However, the current "best-practice" recommendation is to set all environment variables (and other configuration) using config.nu and the autoload directories below.

2. config.nu is typically used to override default Nushell settings, define (or import) custom commands, or run any other startup tasks.

3. *.nu files in $nu.vendor-autoload-dirs are loaded. These directories are intended for vendors' and package managers' startup files.

4. *.nu files in $nu.user-autoload-dirs are loaded. These files may be used for any startup tasks and are a good way to modularize the configuration.

5. login.nu runs commands or handles configuration that should only take place when Nushell is running as a login shell.

By default, env.nu, config.nu, and login.nu are read from the $nu.default-config-dir directory. For example:

$nu.default-config-dir
# macOS
# => /Users/me/Library/Application Support/nushell
# Linux
# => /home/me/.config/nushell
# Windows
# => C:\Users\me\AppData\Roaming\nushell

The first time Nushell is launched, it will create the configuration directory and an empty (other than comments) env.nu and config.nu.

$env.config.buffer_editor = 'code'

Common Configuration Tasks in config.nu:

config.nu is commonly used to:

• Set environment variables for Nushell and other applications
• Set Nushell settings in $env.config
• Load modules or source files so that their commands are readily available
• Run any other applications or commands at startup

Set Environment Variables

Path Configuration

As with most shells, Nushell searches the environment variable named PATH (or variants).

When Nushell is launched, it usually inherits the PATH as a string. However, Nushell automatically converts this to a Nushell list for easy access. This means that you can append to the path using, for example:

$env.path ++= ["~/.local/bin"]

The Standard Library also includes a helper command. The default path add behavior is to prepend a directory so that it has higher precedence than the rest of the path. For example, the following can be added to your startup config:

use std/util "path add"
path add "~/.local/bin"
path add ($env.CARGO_HOME | path join "bin")

Prompt Configuration

Nushell provides a number of prompt configuration options. By default, Nushell includes:

• A prompt which includes the current directory, abbreviated using ~ if it is (or is under) the home directory.
• A prompt indicator which appears immediately to the right of the prompt. This defaults to > when in normal editing mode, or a : when in Vi-insert mode. Note extra space after the character to provide separation of the command from the prompt.
• A right-prompt with the date and time
• An indicator which is displayed when the current commandline extends over multiple lines - ::: by default

The environment variables which control these prompt components are:

• $env.PROMPT_COMMAND: The prompt itself
• $env.PROMPT_COMMAND_RIGHT: A prompt which can appear on the right side of the terminal
• $env.PROMPT_INDICATOR: Emacs mode indicator
• $env.PROMPT_INDICATOR_VI_NORMAL: Vi-normal mode indicator
• $env.PROMPT_INDICATOR_VI_INSERT: Vi-insert mode indicator
• $env.PROMPT_MULTILINE_INDICATOR: The multi-line indicator

Each of these variables accepts either:

• A string, in which case the component will be statically displayed as that string.
• A closure (with no parameters), in which case the component will be dynamically displayed based on the closure's code.
• null, in which case the component will revert to its internal default value.

$env.PROMPT_COMMAND_RIGHT = ""
# or
$env.PROMPT_COMMAND_RIGHT = {||}

Transient Prompts

Nushell also supports transient prompts, which allow a different prompt to be shown after a commandline has been executed. This can be useful in several situations:

• When using a multi-line prompt, the transient prompt can be a more condensed version.
• Removing the transient multiline indicator and right-prompt can simplify copying from the terminal.

As with the normal prompt commands above, each transient prompt can accept a (static) string, a (dynamic) closure, or a null to use the Nushell internal defaults.

The environment variables which control the transient prompt components are:

• $env.TRANSIENT_PROMPT_COMMAND: The prompt itself after the commandline has been executed
• $env.TRANSIENT_PROMPT_COMMAND_RIGHT: A prompt which can appear on the right side of the terminal
• $env.TRANSIENT_PROMPT_INDICATOR: Emacs mode indicator
• $env.TRANSIENT_PROMPT_INDICATOR_VI_NORMAL: Vi-normal mode indicator
• $env.TRANSIENT_PROMPT_INDICATOR_VI_INSERT: Vi-insert mode indicator
• $env.TRANSIENT_PROMPT_MULTILINE_INDICATOR: The multi-line indicator

$env.TRANSIENT_PROMPT_COMMAND_RIGHT = null
$env.TRANSIENT_PROMPT_MULTILINE_INDICATOR = null

ENV_CONVERSIONS

Certain variables, such as those containing multiple paths, are often stored as a colon-separated string in other shells. Nushell can convert these automatically to a more convenient Nushell list. The ENV_CONVERSIONS variable specifies how environment variables are:

• converted from a string to a value on Nushell startup (from_string)
• converted from a value back to a string when running external commands (to_string)

ENV_CONVERSIONS is a record, where:

• each key is an environment variable to be converted
• each value is another record containing a:

  {
    from_string: <closure>
    to_string: <closure>
  }

To add an additional conversion, merge it into the $env.ENV_CONVERSIONS record. For example, to add a conversion for the XDG_DATA_DIRS variable:

$env.ENV_CONVERSIONS = $env.ENV_CONVERSIONS | merge {
    "XDG_DATA_DIRS": {
        from_string: {|s| $s | split row (char esep) | path expand --no-symlink }
        to_string: {|v| $v | path expand --no-symlink | str join (char esep) }
    }
}

LS_COLORS

As with many ls-like utilities, Nushell's directory listings make use of the LS_COLORS environment variable for defining styles/colors to apply to certain file types and patterns.

Nushell Settings in the $env.config Record

Changing Settings in the $env.config Record

The primary mechanism for changing Nushell's behavior is the $env.config record. While this record is accessed as an environment variable, unlike most other variables it is:

• Not inherited from the parent process. Instead, it is populated by Nushell itself with certain defaults.
• Not exported to child processes started by Nushell.

To examine the current settings in $env.config, just type the variable name:

$env.config

$env.config | table -e | less -R
# or, if bat is installed:
$env.config | table -e | bat -p

An appendix documenting each setting will be available soon. In the meantime, abbreviated documentation on each setting can be viewed in Nushell using:

config nu --doc | nu-highlight | bat
# or
config nu --doc | nu-highlight | less -R

To avoid overwriting existing settings, it's best to simply assign updated values to the desired configuration keys, rather than the entire config record. In other words:

$env.config = {
  show_banner: false
}

$env.config.show_banner = false

Certain keys are themselves also records. It's okay to overwrite these records, but it's best-practice to set all values when doing so. For example:

$env.config.history = {
  file_format: sqlite
  max_size: 1_000_000
  sync_on_enter: true
  isolation: true
}

Remove Welcome Message

To remove the welcome message that displays each time Nushell starts:

1. Type config nu to edit your configuration file.

2. If you receive an error regarding the editor not being defined:

   $env.config.buffer_editor = <path to your preferred editor>
   # Such as:
   $env.config.buffer_editor = "code"
   $env.config.buffer_editor = "vi"
   # Or with editor arguments:
   $env.config.buffer_editor = ["emacsclient", "-s", "light", "-t"]

   Then repeat step 1.

3. Add the following line to the end of the file:

   $env.config.show_banner = false

4. Save and exit your editor.

5. Restart Nushell to test the change.

Additional Startup Configuration

Changing default directories

Some variables that control Nushell startup file locations must be set before Nushell is loaded. This is often done by a parent process such as:

• The terminal application in which Nushell is run

• The operating system or window manager. When running Nushell as a login shell, this will likely be the only mechanism available.

  For example, on Windows, you can set environment variables through the Control Panel. Choose the Start Menu and search for "environment variables".

  On Linux systems using PAM, /etc/environment (and other system-specific mechanisms) can be used.

• A parent shell. For example, exporting the value from bash before running nu.

Startup Variables

The variables that affect Nushell file locations are:

• $env.XDG_CONFIG_HOME: If this environment variable is set, it is used to change the directory that Nushell searches for its configuration files such as env.nu, config.nu, login.nu, and the <config>/autoload directory. The history and plugin files are also stored in this directory by default.

  Once Nushell starts, this value is stored in the $nu.default-config-dir constant. See Using Constants below.

• $env.XDG_DATA_HOME: If this environment variable is set, Nushell sets the $nu.data-dir constant to this value. The data-dir is used in several startup tasks:

  • ($nu.data-dir)/nushell/completions is added to the $env.NU_LIB_DIRS search path.
  • ($nu.data-dir)/vendor/autoload is added as the last path in nu.vendor-autoload-dirs. Files in this directory will be read after the other vendor-auto-load directories, thus overriding any of their settings.

  Note that the directory represented by $nu.data-dir, nor any of its subdirectories, are created by default. Creation and use of these directories is up to the user.

• $env.XDG_DATA_DIRS (Unix Platforms Only): If this environment variable is set, it is used to populate the $nu.vendor-auto-load directories in the order listed. The first directory in the list is processed first, meaning the last one read will have the ability to override previous definitions.

/users/username/dotfiles/nushell

/users/username/dotfiles

# Create an empty temporary directory
let temp_home = (mktemp -d)
# Set the configuration path to this directory
$env.XDG_CONFIG_HOME = $temp_home
# Set the data-dir to this directory
$env.XDG_DATA_HOME = $temp_home
# Remove other potential autoload directories
$env.XDG_DATA_HOME = ""
# Run Nushell in this environment
nu

# Edit config
config nu
# Exit the subshell
exit
# Run the temporary config
nu

# Remove the temporary config directory, if desired
rm $temp_home

Using Constants

Some important commands, like source and use, that help define custom commands (and other definitions) are parse-time keywords. Among other things, this means means that all arguments must be known at parse-time.

In other words, variable arguments are not allowed for parser keywords.

However, Nushell creates some convenience constants that can be used to help identify common file locations. For instance, you can source a file in the default configuration directory using:

source ($nu.default-config-dir | path join "myfile.nu")

Because the constant value is known at parse-time, it can be used with parse-time keywords like source and use.

$nu Constant

To see a list of the built-in Nushell constants, examine the record constant using $nu (including the dollar sign).

NU_LIB_DIRS Constant

Nushell can also make use of a NU_LIB_DIRS constant which can act like the $env.NU_LIB_DIRS variable mentioned above. However, unlike $env.NU_LIB_DIRS, it can be defined and used in config.nu. For example:

# Define module and source search path
const NU_LIB_DIRS = [
  '~/myscripts'
]
# Load myscript.nu from the ~/myscripts directory
source myscript.nu

If both the variable $env.NU_LIB_DIRS and the const NU_LIB_DIRS are defined, both sets of paths will be searched. The constant NU_LIB_DIRS will be searched first and have precedence. If a file matching the name is found in one of those directories, the search will stop. Otherwise, it will continue into the $env.NU_LIB_DIRS search path.

NU_PLUGIN_DIRS Constant

const NU_PLUGIN_DIRS works in the same way for the plugin search path.

The following NU_PLUGIN_DIRS configuration will allow plugins to be loaded from;

• The directory where the nu executable is located. This is typically where plugins are located in release packages.
• A directory in $nu.data-dirs named after the version of Nushell running (e.g. 0.100.0).
• A plugins directory in your $nu.config-path.

const NU_PLUGIN_DIRS = [
  ($nu.current-exe | path dirname)
  ($nu.data-dir | path join 'plugins' | path join (version).version)
  ($nu.config-path | path dirname | path join 'plugins')
]

Colors, Theming, and Syntax Highlighting

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

Configuring Nu as a Login Shell

The login shell is often responsible for setting certain environment variables which will be inherited by subshells and other processes. When setting Nushell as a user's default login shell, you'll want to make sure that the login.nu handles this task.

Many applications will assume a POSIX or PowerShell login shell, and will either provide instructions for modifying the system or user profile that is loaded by POSIX login-shells (or .ps1 file on PowerShell systems).

As you may have noticed by now, Nushell is not a POSIX shell, nor is it PowerShell, and it won't be able to process a profile written for these. You'll need to set these values in login.nu instead.

To find environment variables that may need to be set through login.nu, examine the inherited environment from your login shell by running nu from within your previous login shell. Run:

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

Look for any values that may be needed by third-party applications and copy these to your login.nu. Many of these will not be needed. For instance, the PS1 setting is the current prompt in POSIX shells and won't be useful in Nushell.

When ready, add Nushell to your /etc/shells (Unix) and chsh as discussed in the Installation Chapter.

macOS: Keeping /usr/bin/open as open

Some tools such as Emacs rely on an open command to open files on Mac.

Since Nushell has its own open command with a different meaning which shadows (overrides) /usr/bin/open, these tools will generate an error when trying to use the command.

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

Place this in your config.nu to make it permanent.

The ^ symbol tells Nushell to run the following command as an external command, rather than as a Nushell built-in. After running these commands, nu-open will be the Nushell internal version, and the open alias will call the Mac, external open instead.

For more information, see Running System (External) Commands.

Detailed Configuration Startup Process

This section contains a more detailed description of how different configuration (and flag) options can be used to change Nushell's startup behavior.

Launch Stages

The following stages and their steps may occur during startup, based on the flags that are passed to nu. See Flag Behavior immediately following this table for how each flag impacts the process:

Flag Behavior

Scenarios

• nu:

  • ✅ Makes the Standard Library available
  • ✅ Reads user's plugin.msgpackz file if it exists in the config directory
  • ✅ Sources the default_env.nu file internally
  • ✅ Sources the user's env.nu file if it exists in the config directory
  • ✅ Sources the default_config.nu file internally
  • ✅ Sources user's config.nu file if it exists if it exists in the config directory
  • ❌ Does not read personal login.nu file
  • ✅ Enters the REPL

• nu -c "ls":

  • ✅ Makes the Standard Library available
  • ✅ Reads user's plugin.msgpackz file if it exists in the config directory
  • ✅ Sources the default_env.nu file internally
  • ❌ Does not source the user's env.nu
  • ❌ Does not read the internal default_config.nu file
  • ❌ Does not read the user's config.nu file
  • ❌ Does not read the user's login.nu file
  • ✅ Runs the ls command and exits
  • ❌ Does not enter the REPL

• nu -l -c "ls":

  • ✅ Makes the Standard Library available
  • ✅ Reads user's plugin.msgpackz file if it exists in the config directory
  • ✅ Sources the default_env.nu file internally
  • ✅ Sources the user's env.nu file if it exists in the config directory
  • ✅ Sources the default_config.nu file internally
  • ✅ Sources user's config.nu file if it exists in the config directory
  • ✅ Sources the user's login.nu file if it exists in the config directory
  • ✅ Runs the ls command and exits
  • ❌ Does not enter the REPL

• nu -l -c "ls" --config foo_config.nu

  • Same as above, but reads an alternative config file named foo_config.nu from the config directory

• nu -n -l -c "ls":

  • ✅ Makes the Standard Library available
  • ❌ Does not read user's plugin.msgpackz
  • ❌ Does not read the internal default_env.nu
  • ❌ Does not source the user's env.nu
  • ❌ Does not read the internal default_config.nu file
  • ❌ Does not read the user's config.nu file
  • ❌ Does not read the user's login.nu file
  • ✅ Runs the ls command and exits
  • ❌ Does not enter the REPL

• nu test.nu:

  • ✅ Makes the Standard Library available
  • ✅ Reads user's plugin.msgpackz file if it exists in the config directory
  • ✅ Sources the default_env.nu file internally
  • ❌ Does not source the user's env.nu
  • ❌ Does not read the internal default_config.nu file
  • ❌ Does not read the user's config.nu file
  • ❌ Does not read the user's login.nu file
  • ✅ Runs test.nu file as a script
  • ❌ Does not enter the REPL

• nu --config foo_config.nu test.nu

  • ✅ Makes the Standard Library available
  • ✅ Reads user's plugin.msgpackz file if it exists in the config directory
  • ✅ Sources the default_env.nu file internally
  • ❌ Does not source the user's env.nu (no --env-config was specified)
  • ✅ Sources the default_config.nu file internally. Note that default_config.nu is always handled before a user's config
  • ✅ Sources user's config.nu file if it exists in the config directory
  • ❌ Does not read the user's login.nu file
  • ✅ Runs test.nu file as a script
  • ❌ Does not enter the REPL

• nu -n --no-std-lib (fastest REPL startup):

  • ❌ Does not make the Standard Library available
  • ❌ Does not read user's plugin.msgpackz
  • ❌ Does not read the internal default_env.nu
  • ❌ Does not source the user's env.nu
  • ❌ Does not read the internal default_config.nu file
  • ❌ Does not read the user's config.nu file
  • ❌ Does not read the user's login.nu file
  • ✅ Enters the REPL

• nu -n --no-std-lib -c "ls" (fastest command-string invocation):

  • ❌ Does not make the Standard Library available
  • ❌ Does not read user's plugin.msgpackz
  • ❌ Does not read the internal default_env.nu
  • ❌ Does not source the user's env.nu
  • ❌ Does not read the internal default_config.nu file
  • ❌ Does not read the user's config.nu file
  • ❌ Does not read the user's login.nu file
  • ✅ Runs the ls command and exits
  • ❌ Does not enter the REPL