The Question Mark - blog by Mark Volkmann

Nushell

Overview

Nushell is “a new type of shell”. It brings the Unix philosophy of connecting small commands with pipes to structured data such as lists, records, and tables. Nushell runs on Linux, macOS, and Windows.

This article was updated for Nushell 0.115.1 on September 26, 2026. Nushell is still evolving, so check the release notes when upgrading.

Nushell is implemented in Rust. And like Rust, Nushell produces helpful, nicely formatted error messages.

Nushell includes the Nu language which excels at processing streams of structured data. This provides features that are somewhat like SQL for databases. It also has similarities to the Python-based Pandas data analysis library. These are features not typically seen in shell environments.

Nushell continues the UNIX tradition of commands whose input can be piped in from a previous command and whose output can be piped to a subsequent command. A series of commands separated by the pipe character | is referred to as a “pipeline”. Many commands stream their output, allowing the next command to start before the previous command has finished producing all its data. Other commands, such as sorting, need to collect their input first.

Nushell distinguishes returning a value from printing it. echo returns its arguments as data whereas print writes to the terminal. In a script or custom command, only the final expression’s value is returned. For example, let a = 2; let b = 3; $a + $b returns 5. Use print for messages that should appear even when another expression follows.

Commands are syntax-highlighted as they are typed, and the editor provides completion and command history.

You don’t have to commit to making Nushell your default shell. Just enter nu periodically to try it, and exit to return to your current shell. Over time you may decide you like it enough to make it your default shell.

Terminology

The term “pipeline” was described earlier. A pipeline can span multiple lines by ending lines with |. Parentheses can also enclose a multiline pipeline. The interactive editor supports multiline input. An unfinished expression such as an unclosed parenthesis can be continued on the next line. Nushell does not use \ as a line continuation character like Bash.

Commands that take no input and produce output are sometimes referred to as “inputs” or “sources”. An example is the open command which loads a file.

Commands that take input and transform it are referred to as “filters”. Examples include the where and sort-by commands.

Commands that take input and display it or write it somewhere such as a file are referred to as “outputs” or “sinks”. An example is the save command.

Installing

There are many options for installing Nushell.

If you have Rust and the required build tools installed, enter cargo install nu --locked. This compiles Nushell, which can take several minutes. Cargo normally installs the nu executable in $HOME/.cargo/bin; make sure that directory is on your PATH. Plugins are installed separately.

If you are on macOS and have Homebrew installed, enter brew install nushell. Prebuilt binaries for Linux, macOS, and Windows can also be downloaded from the release page.

For more information, see Installing Nu.

If you are interested in peeking at the source code, clone the GitHub repository.

To build Nushell locally, enter cargo build --release from that repository. To build the entire workspace, including its plugin packages, use cargo build --release --workspace.

Upgrading

Use the same installation method to upgrade:

  • For Homebrew, enter brew update and then brew upgrade nushell.
  • For Cargo, enter cargo install nu --locked. If a newer Rust toolchain is required, update it with rustup update first.
  • For downloaded binaries, replace them with the binaries for the desired release.

Enter nu --version or nu -v to check the installed version. Start a new Nushell session to use the upgraded executable. Update separately installed plugins to compatible versions as well.

Getting Started

After installing Nushell, enter nu in a terminal to start a shell.

For help, enter help. For a list of available commands, enter help commands. The list depends on your Nushell build and the plugins, modules, and custom commands that are loaded.

For help on a specific command, enter help {command-name} or {command-name} --help. In Nushell version 0.115.1 there are 567 commands. For more detail, see the Command Reference.

To search for commands, use help --find, for example help --find string. You can also process help as structured data:

help commands | select name description | where name starts-with 'str '

Like in other shells, commands are executed by typing them and pressing the return key. Nushell has command recall and completion like the Fish and Zsh shells. Command recall also supports multiline command editing.

When a command not defined by Nushell is encountered, the directories in $env.PATH are searched for a matching executable. To run an executable that has the same name as a Nushell command, prefix the command name with ^. For example, ^find . -name '*.ts' runs the external find executable. It does not invoke a command or alias from a parent shell.

For detailed documentation, see the Book. For more help, join the Nushell Discord channel.

Subcommands

Subcommands provide a way of grouping commands under a common “namespace”. Examples include date, from, http, into, math, path, random, str, to, and url. Use help {namespace} to see the available subcommands.

The date subcommands include from-human, humanize, list-timezone, now, and to-timezone. To format a date, use format date. To examine its components, use date now | into record.

The from subcommands parse data in formats such as CSV, JSON, TOML, and YAML. The result may be a table, record, list, or scalar, depending on the data. For example, '{"foo": 1, "bar": 2}' | from json | get bar returns 2. Additional parsers can be provided by plugins.

The into subcommands convert values to another type. Examples include binary, bool, datetime, duration, filesize, float, int, and string. For example, '19' | into int gives the integer 19.

The math subcommands perform calculations. They include abs, avg, cbrt, ceil, cos, exp, floor, ln, log, max, median, min, mode, product, round, sin, sqrt, stddev, sum, tan, variance, and more. Use ordinary expressions for arithmetic, for example 2 + 3 * 4.

The path subcommands operate on file paths. The table below describes these and shows the result of entering echo ~/Documents/demo.txt | path {subcommand}.

SubcommandDescription
basenamereturns the filename portion of a path (demo.txt)
dirnamereturns the parent directory path (~/Documents)
existstests whether a path exists
expandexpands a path to an absolute path (/Users/mark/Documents/demo.txt)
joinjoins path components; for example, 'Documents' | path join demo.txt
returns ~/Documents/demo.txt
parsereturns a record including parent (directory path), stem (filename w/o extension), and extension
relative-toreturns a path relative to another path
splitreturns a list of path components
typereturns a type such as file, dir, or symlink, or an empty string for a nonexistent path

The str subcommands perform string operations. They are camel-case, capitalize, contains, distance, downcase, ends-with, escape-regex, expand, index-of, join, kebab-case, length, lowercase, pascal-case, replace, reverse, screaming-snake-case, snake-case, starts-with, substring, title-case, trim, upcase, and uppercase. Also see the command char and the format subcommands.

The to subcommands serialize data into formats such as CSV, JSON, and YAML. They include csv, html, json, md, text (or txt), toml, tsv, xml, and yaml (or yml). These are commonly piped to save to write the result to a file. The appropriate input shape depends on the format. For example, CSV represents rows and columns, while JSON can represent nested data.

The url subcommands include build-query, decode, encode, join, parse, and split-query. For example:

'https://example.com/blog?tag=nu' | url parse | get host # example.com

Configuration

Nushell configuration uses Nu scripts rather than TOML. config.nu is the main interactive configuration file. Its path is available as $nu.config-path. env.nu can set environment variables and runs before config.nu. Its path is available as $nu.env-path. Login shells can also read login.nu.

To edit the main configuration file with Vim, enter vim $nu.config-path. To edit it with VS Code, enter code $nu.config-path. You can also set $env.config.buffer_editor = 'code' and use config nu. Use config env to edit env.nu.

The current settings are in the $env.config record. Enter $env.config to inspect them, or config nu --doc to read documented configuration examples. Assign a field to change a setting immediately:

$env.config.show_banner = false
$env.config.table.mode = 'rounded'

To persist a setting, add the assignment to config.nu. Editing the file does not automatically change a running shell. Start a new session, or use source $nu.config-path to execute the file again. Sourcing repeats all its commands, so additions to lists such as PATH will be repeated.

After modifying the config.nu file, to start a new session that uses the changes, enter exec nu. To reapply the config within the existing session, enter source $nu.config-path.

To define abbreviations, which are like aliases in other shells, add the following in the config file:

$env.config.abbreviations = {
  abbrev1: 'command 1'
  abbrev2: 'command 2'
  ...
}

For details, see Configuration.

Prompt

Prompt components are configured through environment variables. They can hold strings or closures that compute strings. For example, add the following to config.nu:

$env.PROMPT_COMMAND = {|| $"🦀ν (ansi yellow)(pwd)(ansi reset)" }
$env.PROMPT_INDICATOR = $"(ansi green)▶ (ansi reset)"
$env.PROMPT_COMMAND_RIGHT = ''

🦀 is for the Rust mascot Ferris and ν is the Greek letter nu. The closure is evaluated again for each prompt, so the working directory stays current.

Another option is Starship, which has many more options and works with multiple shells. See Nushell’s third-party prompt setup for integration instructions.

Startup Commands

Define aliases, custom commands, and imports directly in config.nu. For example:

alias cls = clear

# Changes to the directory stored in JS_DIR.
def --env cdjs [] { cd $env.JS_DIR }

# Changes to the directory stored in RUST_DIR.
def --env cdrust [] { cd $env.RUST_DIR }

The --env flag allows these custom commands to change the caller’s environment, including the working directory. Set JS_DIR and RUST_DIR to your project directories before using them. Aliases can also use cd, for example alias cdh = cd ~.

Table Settings

Table borders can be customized with $env.config.table.mode. Run table --list to see the supported themes. Supported table.mode values include:

  • basic: uses +, -, and | characters for borders
  • compact: omits outer left and right borders
  • compact_double: like compact, but uses double lines for borders
  • heavy: thicker border on every cell
  • light: horizontal line below header and no other borders
  • none: no borders
  • reinforced: border on every cell with thick table corners
  • rounded: border on every cell and rounded table corners (my favorite)
  • thin: border on every cell
  • with_love: heart characters for borders

For example:

$env.config.table.mode = 'rounded'
$env.config.table.index_mode = 'never'

The second assignment hides the index column globally. For one pipeline, use ls | table --index false. To override the theme for one pipeline, use ls | table --theme compact. These options affect rendering, not the underlying data.

Colors

Customize colors through $env.config.color_config. Keys include header, row_index, separator, bool, int, string, and many more. Values can be color names or style records. For example:

$env.config.color_config.header = { fg: 'red', attr: 'b' }
$env.config.color_config.row_index = 'dark_gray'
$env.config.color_config.separator = 'dark_gray'
$env.config.color_config.int = 'green'
$env.config.color_config.string = 'white'

Run ansi --list to see available ANSI styles. For more options, see Coloring and Theming.

Line Editor

Nushell uses Reedline for line editing, history, and completion.

Press the tab key for completions. Use the arrow keys to move to an option and press the return key to select the highlighted option.

For example:

$env.config.edit_mode = 'vi'
$env.config.history.ignore_space_prefixed = true
$env.config.completions.algorithm = 'fuzzy'

For Emacs-style editing, use emacs instead of vi. The history setting above excludes commands starting with a space from saved history. The completion algorithm can be prefix or fuzzy.

PATH and Environment

$env.PATH contains the directories searched for executables as a list. To display them in a table, enter $env.PATH. To prepend a directory:

$env.PATH = ($env.PATH | prepend ($env.HOME | path join '.cargo' 'bin'))

Nushell inherits environment variables from its parent process, which need not be another shell. To define an environment variable, use an assignment such as:

$env.GITHUB_USER = 'mvolkmann'

Put assignments in your configuration file to make them available in new sessions. When configuring Nushell as a login shell, also review the environment setup previously performed by your old shell’s startup files.

Data Types

Unlike shells where command input and output are primarily text, Nushell supports primitive and structured data types. The following table lists commonly used types and annotations.

TypeDescription or example
anyaccepts any type; useful for untyped command parameters
binaryraw bytes, for example 0x[01 FF]
booltrue or false
cell-patha path into structured data, for example $.address.city
closureexecutable code with parameters, for example {|n| $n * 2}
datetimea date and time, for example 2026-09-26T12:00:00-05:00
durationa time interval, for example 2hr + 30min
filesizea byte count, for example 10MB or 10MiB
floata 64-bit floating-point number, for example 3.14
globa glob pattern value; convert a string with into glob
inta signed 64-bit integer
listan ordered collection, for example [red green blue]
nothingthe type of null
numbera parameter annotation accepting either int or float
rangea numeric sequence, for example 1..5 or 1..<5
recordnamed fields, for example {name: Mark, score: 19}
stringtext
tablea list of records, typically with matching columns

A filepath is normally represented as a string. Parameter types such as path help Nushell parse command arguments.

Integers do not have unlimited precision. Floating-point values are approximate, so arithmetic can have rounding effects. Duration units include ns, us, ms, sec, min, hr, day, and wk. Month and year durations are not supported because their lengths vary.

The ability to specify single-word strings without delimiters in lists and command arguments is one of my favorite features! For example:

let colors = [red orange yellow green blue purple]

Bare words are context-dependent: at the start of a pipeline, a word is generally interpreted as a command name. Quote strings when an expression could otherwise be ambiguous.

Pipe a value to describe to inspect its type:

42 | describe # int
3.14 | describe # float
date now | describe # datetime

For full details, see Types of Data.

Type Conversions

Use into subcommands for conversions, from subcommands to parse formats, and to subcommands to serialize data.

InputDesired resultCommand
integer, float, boolean, or datestring representationinto string
list of stringsa single joined stringstr join, optionally with a separator
numeric stringintegerinto int
numeric stringfloating-point numberinto float
boolean stringbooleaninto bool
date stringdate/timeinto datetime
string with a separatorlistsplit row separator
JSON stringstructured valuefrom json
structured valueJSON stringto json
date/timecomponent recordinto record

describe returns a type description, not a string representation of the value.

For example:

'2021-03-21T14:30:00+00:00' | into datetime | format date '%B %-d, %Y'
# March 21, 2021

Use format date --list to see the supported formatting specifiers.

This handy custom command joins input values with newlines. Consider adding it to config.nu:

# Converts input values to strings and joins them with newlines.
def as-lines [] {
  $in | each {|item| $item | into string } | str join (char newline)
}

1..3 | as-lines
# 1
# 2
# 3

Strings

Strings can use single quotes, double quotes, or backticks. Double-quoted strings interpret escape sequences such as \n and \t. Single quotes and backticks are useful when those characters should remain literal.

String interpolation uses $"..." or $'...', with expressions in parentheses. For example:

let x = 19
$"x is ($x)" # x is 19

let a = 3
let b = 5
$"product of ($a) and ($b) is ($a * $b)" # product of 3 and 5 is 15

is-empty determines whether a string, list, record, or table is empty:

'Mark' | is-empty # false
'' | is-empty # true

The =~ and !~ operators test whether a string matches a regular expression. Use str contains to test for a literal substring.

'foobarbaz' =~ 'b.r' # true
'foobarbaz' !~ '^bar' # true
'foobarbaz' | str contains 'bar' # true

The lines command splits a string at line endings:

let s = "This\nhas\nthree lines."
$s | lines # [This has 'three lines.']

For more examples, see Working with Strings.

Ranges

A range describes a numeric sequence. 2..4 includes 2, 3, and 4, while 2..<4 excludes 4. 4..2 counts down, and -2..2 includes -2 through 2. Floating-point bounds are supported, for example 1.2..4.0. An explicit second value sets the step: 2..4..10 produces 2, 4, 6, 8, and 10.

An omitted start defaults to zero, so ..10 is equivalent to 0..10. An omitted end makes the range unbounded. Limit an unbounded range with a command such as take before collecting it.

3..7 | first # 3
3..<7 | last # 6
0.. | take 3 # [0 1 2]

Types With Units

Duration values with different units can be added. For example, 2hr + 57min + 11sec (my best marathon time).

File sizes also support units and arithmetic. MB uses powers of 1000; MiB uses powers of 1024. For example, 2MB + 57KB + 11B is a file size. When comparing a size from ls, use a file-size value such as size > 1KB.

Incompatible types cause an error. For example, adding a duration to a file size with 3hr + 2MB is invalid.

Lists

A list is an ordered collection of values. Create one with expressions in square brackets separated by spaces or commas. For example, [foo bar baz] or [foo, bar, baz].

To transform each item, use each with a closure. The closure declares the variable holding the current item between | characters. To also obtain each item’s index, insert enumerate:

let names = [Mark Tami Amanda Jeremy]
$names | each {|name| $"Hello, ($name)!" }
$names | enumerate | each {|entry| $"($entry.index + 1)) ($entry.item)" }

The second pipeline produces the strings 1) Mark, 2) Tami, and so on. There is no implicit $it variable and no each --numbered flag. You can name a closure parameter it, but you must declare it explicitly.

The split row command creates a list from a string based on a delimiter:

let colors = ('red,green,blue' | split row ',')
$colors.1 # green
$colors | length # 3
$colors | is-empty # false
'blue' in $colors # true
'yellow' not-in $colors # true

List indexes start at zero. Use $name.index or get index to access one item.

The where command filters a list:

let colors = [red orange yellow green blue purple]
$colors | where {|color| $color | str ends-with 'e' }
# [orange blue purple]

let scores = [7 10 8 6 7]
$scores | where {|score| $score > 7 } # [10 8]

any tests whether at least one item satisfies a condition. all tests whether every item satisfies it. Both take closures:

let scores = [7 10 8 6 7]
$scores | any {|score| $score > 7 } # true
$scores | any {|score| $score mod 2 == 1 } # true
$scores | all {|score| $score >= 3 } # true
$scores | all {|score| $score mod 2 == 0 } # false

append and prepend return new lists. A list argument contributes its elements; wrap it in another list if you want to append a nested list as one item.

let colors = [yellow green]
let colors = ($colors | prepend red | append purple)
$colors # [red yellow green purple]

flatten removes a level of nesting:

[1 [2 3] 4 [5 6]] | flatten # [1 2 3 4 5 6]
[[1 2] [3 [4 5 [6 7 8]]]] | flatten | flatten | flatten
# [1 2 3 4 5 6 7 8]

reduce combines values using a closure with item and accumulator parameters, in that order. --fold supplies the initial accumulator. Without it, the first item becomes the initial accumulator.

let scores = [3 8 4]
$scores | reduce {|item, acc| $acc + $item } # 15
$scores | math sum # 15, an easier approach
$scores | reduce --fold 1 {|item, acc| $acc * $item } # 96
$scores | enumerate | reduce --fold 0 {|entry, acc|
  $acc + $entry.index * $entry.item
} # 16

Tables

A table is a list of records. The compact literal syntax starts with a list of column names, followed by a semicolon and lists of row values:

let scores = [[Name Score]; [Mark 19] [Tami 21]]
$scores

This renders as a table similar to:

╭───┬──────┬───────╮
│ # │ Name │ Score │
├───┼──────┼───────┤
│ 0 │ Mark │    19 │
│ 1 │ Tami │    21 │
╰───┴──────┴───────╯

SQL-like filters retrieve data from a table:

let scores = [[Name Score]; [Mark 19] [Tami 21]]
$scores | where Name == 'Tami' | get Score # [21]
$scores | where {|row| $row.Name == 'Tami' } | get Score | first # 21

Filtering a table still returns a table, even if only one row matches. Getting a column returns a list. Use first or get 0 when you need one value.

Use a record for a single object:

let data = {color: yellow, flavor: vanilla}
$data.color # yellow
$data.flavor # vanilla

Multiline table literals work normally:

let sports = [
  [name players];
  [baseball 9]
  [basketball 5]
  [football 11]
  [hockey 6]
]
let sport = 'basketball'
let players = ($sports | where name == $sport | get players | first)
$"The number of active players in ($sport) is ($players)."

Records and tables can contain nested structured data. For example:

let person = {
  name: 'Mark Volkmann'
  address: {
    street: '123 Some Street'
    city: Somewhere
    state: MO
    zip: '12345'
  }
}
$person.address.city # Somewhere
$person | to json --indent 2

This serializes to a JSON object with a nested address object. A table would serialize to an array of objects, including for a one-row table.

Operators

Nushell supports the following operators, among others:

OperatorDescription
+, -, *, /arithmetic
//floor division
**exponentiation
modmodulo
==, !=equality and inequality
<, <=, >, >=ordering comparisons
=~, !~regex match and non-match
in, not-inmembership and non-membership
and, or, xor, notBoolean operations
++concatenate lists or strings
starts-with, ends-withstring prefix and suffix comparisons

Parentheses group expressions and capture the result of command pipelines. For example, let a = 2; let b = 3; $a * $b returns 6. There is no leading = to enter a separate math mode.

When passing a calculation as a command argument, use parentheses: print (2 + 3). In expression positions, such as after let value =, they are often unnecessary.

See Operators for the complete list.

Working with Numbers

Use arithmetic to increment or decrement a value. Immutable let bindings can be shadowed, or use mut for a mutable variable:

mut score = 2
$score += 1
$score # 3

To update numbers in a table column:

[[Name Size]; [Mark 33] [Tami 28]] | update Size {|row| $row.Size + 1 }

For semantic version numbers, Nushell 0.115.1 has semver bump:

'1.2.3' | semver bump major # 2.0.0
'1.2.3' | semver bump minor # 1.3.0
'1.2.3' | semver bump patch # 1.2.4

Working with URLs

Use http get to retrieve data from a URL. JSON responses are normally decoded into structured values automatically. Use --raw when you want the response without format conversion.

The website JSONPlaceholder provides free sample JSON data. The following example gets three incomplete TODOs for user 5:

http get https://jsonplaceholder.typicode.com/todos |
  where userId == 5 and completed == false |
  sort-by title | take 3

The http post command sends an HTTP POST request. Specify the content type when sending JSON:

For a multiline command, enclose the invocation in parentheses:

(http post --content-type application/json
  https://jsonplaceholder.typicode.com/todos
  {title: 'get milk', userId: 5})

JSONPlaceholder simulates creation without permanently storing the TODO. Nushell also provides http put, http patch, http delete, http head, and http options. See help http for the available subcommands.

Common UNIX Commands

Many common UNIX commands have Nushell implementations. Their options and output can differ from the external utilities with the same names.

CommandDescription
caldisplays a calendar
cdchanges the current working directory
clearclears the terminal
cpcopies files or directories
date nowgets the current date and time
dugets disk usage information
echoreturns values as pipeline data
exitexits Nushell, optionally with a status code
helpdisplays help
historyreturns command history
killsends a signal to a process
lslists files and directories as a table
mkdircreates directories, including missing parents
mvmoves files or directories
openreads a file, parsing supported formats
printprints values to the terminal
psreturns process information
pwdreturns the current working directory
rmremoves files or directories
sourceruns a Nu script in the current context
whichlocates commands

To change to a subdirectory named “sub”, enter cd sub. Interactive Nushell also supports directory shortcuts such as ../. The cp, mv, and rm commands support --interactive (-i).

Commands such as ls and ps return tables. The sys command has subcommands such as sys host and sys mem. Use cell paths or get to access nested data.

Filters such as where, sort-by, and reverse modify the output. sort-by --reverse (-r) reverses the sort order; --ignore-case (-i) makes string sorting case-insensitive.

# List package.json files in and below the current directory.
ls **/package.json

# List Rust files recursively.
ls **/*.rs

# List files of at least 2 KB, largest first.
ls | where type == file and size >= 2KB | sort-by --reverse size

# List directory names alphabetically.
ls | where type == dir | sort-by name | get name

# Show processes using more than 5% of a CPU, busiest first.
ps | where cpu > 5 | sort-by --reverse cpu

# Show host information.
sys host

# Show temperatures, where supported by the platform.
sys temp

# Show date/time components.
date now | into record

The type strings returned by ls are lowercase, such as file and dir. Directory sizes in a plain ls listing are not recursive totals; use du when that is what you need.

To serialize a table, use a to subcommand, for example ls | to json. save can also choose a serializer based on the output extension:

ls | where type == file and size > 1KB | sort-by --reverse size |
  to html | save big-files.html

ls | where type == file and size > 1KB | sort-by --reverse size |
  save big-files.csv

The output files must not already exist; use save --force to replace them. Automatic serialization also works for other supported extensions such as .json. save --raw bypasses extension-based conversion.

To compute the total size of files in Cargo’s default binary directory:

ls ($env.HOME | path join '.cargo' 'bin') |
  where type == file | get size | math sum

This assumes Cargo uses its default installation directory.

Aliases

To create an alias, enter alias name = command. For example, alias cls = clear. The command can be built in, external, or custom, and fixed arguments can be included. Additional arguments can be supplied when using the alias.

alias df = format date
date now | df '%B %-d, %Y'

Put aliases directly in config.nu to make them available in new sessions. An alias represents a command invocation, not an entire pipeline. Use a custom command for a pipeline:

# Lists the ten busiest processes.
def top [] { ps | sort-by --reverse cpu | first 10 }

Custom Commands

Define a custom command with def name [parameters] { body }. Names can contain hyphens. Use [] when there are no parameters. Parameter values are accessed with $ before their names.

# Lists processes using at least the specified CPU percentage.
def topn [pct: number] {
  ps | where cpu >= $pct | sort-by --reverse cpu
}

topn 5

A custom command returns the value of its last expression, or a value explicitly supplied to return. Use print for terminal messages; multiple echo statements do not concatenate into the return value.

# Describes whether a number is big or small.
def evaluate [n: int] {
  let word = if $n > 5 { 'big' } else { 'small' }
  $"The number ($n) is ($word)."
}

evaluate 1 # The number 1 is small.
evaluate 9 # The number 9 is big.

Parameter types are optional but improve documentation and error messages. Parameters are separated by spaces when calling a command:

# Computes the sum of two numbers.
def sum [
  n1: number # first number
  n2: number # second number
] {
  $n1 + $n2
}

sum 1 2 # 3

Pipeline input is available as $in. For example:

# Doubles a number supplied through the pipeline.
def double []: number -> number { $in * 2 }

3 | double # 6

Named parameters (flags) start with --. An optional short name follows in parentheses. A flag with no value type is a Boolean switch; a typed flag that is not provided has the value null unless a default is set.

# Prints a message, optionally in a named ANSI color.
def log-color [text: string, --color (-c): string] {
  if $color == null {
    print $text
  } else {
    print $"(ansi $color)($text)(ansi reset)"
  }
}

log-color 'Giraffes are cool!' --color yellow

Custom commands can accept closures. Use do to call a closure directly, or pass it to a command such as each:

# Applies a closure to each value in a list.
def map [values: list, code: closure] {
  $values | each $code
}

map [Mark Tami Amanda Jeremy] {|name| $"Hello, ($name)!" }

A rest parameter starts with ... and collects additional positional arguments into a list. It must be last, but its name does not have to be rest. The type annotation describes each additional argument:

# Formats the sum of any number of integer arguments.
def labelled-sum [label: string, ...values: int] {
  $"($label) = ($values | math sum)"
}

labelled-sum 'sum of scores' 3 7 19 # sum of scores = 29

Help works just as it does for built-in commands: help labelled-sum. Comments immediately before a definition and after parameter declarations supply documentation.

Define a subcommand by quoting a name containing spaces:

# Parent command for the rmv examples.
def rmv [] { help rmv }

# Doubles a number.
def 'rmv double' [n: number] { $n * 2 }

# Increments a number.
def 'rmv increment' [n: number] { $n + 1 }

rmv double (rmv increment 3) # 8

Put definitions in config.nu, or load them from another Nu file with source. Use def --env when a command must preserve environment changes in its caller, for example a command that uses cd. See Custom Commands.

Variables

Variables are distinct from environment variables. let creates an immutable binding; mut creates a mutable one. const defines a value evaluated at parse time, which can be useful for imports and other parser keywords.

let greeting = 'Hello'
mut count = 1
$count += 1
$"($greeting), count is ($count)" # Hello, count is 2

Variables are scoped to the block in which they are defined. An immutable binding can be shadowed with another let binding. To assign a pipeline result, use let names = (ls | get name). Parentheses also allow pipeline results to be passed as command arguments.

To concatenate values as text, use interpolation:

let v1 = 'Nu'
let v2 = 'shell'
let v3 = $"($v1)($v2)"
$v3 # Nushell

Environment Variables

Environment variables are stored in the $env record. They are passed to external programs, with values converted as needed for the operating system’s string-based environment. Nushell’s own configuration record is not exported as a normal environment variable.

$env.GITHUB_USER = 'mvolkmann'
$env.GITHUB_USER

An assignment changes the environment in the current scope. Persist it by adding it to your startup configuration. Use hide-env NAME to remove a variable from the current environment.

To list variables as rows with names and values:

$env | transpose name value

To set a variable for just one external command, use an environment prefix, for example NODE_ENV=production node app.js.

open Command

The open command reads a file or SQLite database and parses recognized formats into structured data. No other databases are currently supported. For example, CSV becomes a table and a JSON object becomes a record. The available conversions depend on the commands loaded into the shell.

Consider a file named scores.csv containing:

Name,Score
Mark,19
Tami,21
Amanda,17
Jeremy,15

open scores.csv displays the rows as a table. To extract information from a JSON file:

open package.json | get scripts | transpose name command

This returns one row per script, with the columns name and command.

Use table --index false to hide row indexes for a particular display. For plain output without table headings, extract and format the values instead, for example open scores.csv | get Name | str join (char newline).

Plain text is not automatically rendered with bat syntax highlighting. If you want that presentation, install and run bat separately. open --raw skips format parsing; for text processing, open --raw file.txt | decode utf-8 explicitly decodes the bytes as text.

For example, suppose languages.txt contains:

Go|2012|Rob Pike
Java|1995|James Gosling
JavaScript|1995|Brendan Eich
Python|1991|Guido van Rossum
Ruby|1995|Yukihiro Matsumoto
Rust|2010|Graydon Hoare
TypeScript|2012|Anders Hejlsberg

Parse the lines into columns, convert the year to an integer, and sort:

open --raw languages.txt | decode utf-8 | lines |
  split column '|' Language Year Creator |
  into int Year | sort-by Year

If a file extension does not match its format, read the raw data and parse it explicitly:

open --raw really-json.txt | decode utf-8 | from json

Use http get instead of open to read a URL:

http get https://jsonplaceholder.typicode.com/todos |
  where userId == 2 and completed == true | sort-by title

SQLite support

Supposes we have a SQLite database in the file todos.db which contains the table todos. Entering open todos.db might display the following:

╭─────────────────┬─────────────────────────────────────────╮
│                 │ ╭─#─┬─id──┬──description──┬─completed─╮ │
│ todos           │ │ 0 │ 107 │ buy milk      │         1 │ │
│                 │ │ 1 │ 121 │ cut the grass │         0 │ │
│                 │ │ 2 │ 161 │ foo           │         1 │ │
│                 │ │ 3 │ 162 │ bar           │         1 │ │
│                 │ │ 4 │ 163 │ baz           │         1 │ │
│                 │ ╰─#─┴─id──┴──description──┴─completed─╯ │
│                 │ ╭─#─┬─name──┬─seq─╮                     │
│ sqlite_sequence │ │ 0 │ todos │ 163 │                     │
│                 │ ╰─#─┴─name──┴─seq─╯                     │
╰─────────────────┴─────────────────────────────────────────╯

open todos.db | query db “select description from todos where completed=1”

╭─#─┬─description─╮
│ 0 │ buy milk    │
│ 1 │ foo         │
│ 2 │ bar         │
│ 3 │ baz         │
╰─#─┴─description─╯

Table Commands

The following are some useful commands for working with tables and lists. Use help command-name for their full signatures and examples.

CommandDescription
alltests whether all rows satisfy a closure
anytests whether at least one row satisfies a closure
append, prependadds values at the end or beginning
columnsreturns column names
compactremoves null values; can check specified table columns
drop nremoves the last n rows
drop column nremoves the last n columns
eachtransforms rows with a closure
enumeratepairs each item with its index
every nreturns every nth row; --skip skips those rows instead
first, lastreturns one item, or a list when a count is supplied
flattenremoves a level of nesting
format patternformats rows as strings using named fields
getextracts values by cell path
group-bygroups rows by a column or closure
headerspromotes the first row’s values to column names
histogramcomputes counts, percentages, and frequency bars
insert, update, upsertadds, changes, or adds-or-changes fields
is-emptytests whether the input is empty
lengthcounts rows or items
mergecombines columns from records or tables
movereorders columns
parseextracts fields from strings using a pattern
rejectremoves columns or rows
renamerenames columns
reversereverses row order
roll up, roll downcycles rows using --by n
rotaterotates a table; --ccw selects counterclockwise rotation
selectchooses columns or rows
shufflerandomly reorders rows
skipskips a number of rows
skip until, skip whileskips rows based on a condition
sliceselects a range of rows
sort-bysorts by one or more columns
split columnsplits strings into named columns
tablerenders structured data as text
taketakes a number of rows
take until, take whiletakes rows based on a condition
transposeexchanges rows and columns
uniqremoves duplicate rows or items
wherefilters rows using a condition
wrapputs values into a named column

For example, list the three largest TypeScript files in the current directory:

ls *.ts | select name size | sort-by --reverse size | first 3

Add | select 1 to return the second selected row as a one-row table. Use | get 1 if you want the row as a record instead. Glob examples assume matching files exist.

all and any Commands

These commands return Boolean results rather than filtered tables:

let scores = [[Name Score]; [Mark 19] [Tami 21]]
$scores | all {|row| $row.Score >= 20 } # false
$scores | any {|row| $row.Score >= 20 } # true

append and prepend Commands

Append or prepend records or another table:

let primaryColors = [
  [name red green blue];
  [red 255 0 0]
  [green 0 255 0]
  [blue 0 0 255]
]
let purple = {name: purple, red: 255, green: 0, blue: 255}
let white = {name: white, red: 255, green: 255, blue: 255}
$primaryColors | append $purple | prepend $white

This produces five rows. No extra flatten workaround is needed.

each Command

each transforms each input item with a closure:

ls *.nu | each {|file| $"($file.name) is ($file.size)." } |
  str join (char newline)

Use for when the purpose is side effects such as printing, rather than collecting a list of results:

for name in [Mark Tami] {
  print $"Hello, ($name)!"
}

is-empty Command

[[Name Score]; [Mark 19] [Tami 21]] | is-empty # false
[] | is-empty # true
[[Name Score]; [Mark 19]] | where Score > 30 | is-empty # true

flatten Command

flatten can also bring fields from nested records into the outer table:

[{name: Mark, address: {city: Somewhere, state: MO}}] | flatten

The result has columns name, city, and state.

format pattern Command

Format each row into a string by naming its fields inside braces:

ls | format pattern '{name} is a {size} {type} and was modified {modified}.'

For more control over formatting, use each with string interpolation.

from Command

from subcommands parse serialized data. For example:

let data = "Name,Score\nMark,19\nTami,21\n"
$data | from csv

For a file with a recognized extension, open scores.csv performs this conversion.

get Command

get extracts a value using a cell path. A column from a table is a list; a field from a record can be a scalar. For example:

ls *.ts | sort-by --reverse size | first 3 | get name

Cell paths can access nested fields and list indexes, for example $person.address.city. Use columns to list column names. To select a column by its position, first look up its name:

let data = [[name score]; [Mark 19] [Tami 21]]
let columnIndex = 1
$data | select ($data | columns | get $columnIndex)

group-by Command

Group rows by a column or a closure. By default, group-by produces a record whose keys are group names and whose values are tables of matching rows:

ls | group-by type

The keys might include file and dir. A key is absent if no rows belong to that group. Use an optional cell path to handle that case:

let groups = (ls | group-by type)
$groups.file? | default []

To group by filename extension:

ls | group-by {|file| $file.name | path parse | get extension }

histogram Command

histogram counts occurrences and displays relative frequencies:

let data = [
  [name color];
  [Mark yellow]
  [Tami blue]
  [Amanda green]
  [Jeremy yellow]
  [Sally blue]
  [Sam yellow]
]
$data | get color | histogram | sort-by value | select value count percentage

The counts are blue: 2, green: 1, and yellow: 3. Their percentages are 33.33%, 16.67%, and 50.00% of the six observations. The complete output also includes quantile and a text frequency bar.

Use histogram --percentage-type relative to calculate percentages relative to the largest count instead of the total.

split and headers Commands

Use split row, split column, and headers to parse delimited text:

let data = 'name red green blue|red 255 0 0|green 0 255 0|blue 0 0 255'
$data | split row '|' | split column ' ' | headers |
  into int red green blue

The conversion makes the numeric columns integers instead of strings.

Matching Rows

Use where with =~ to filter rows with a regular expression:

ls | where type == file | where name =~ '^c.*\.nu$'

This lists files whose names begin with c and end with .nu. Single quotes preserve the regex backslash.

The match keyword is for pattern-matching control flow, not table filtering:

let status = 'done'
match $status {
  'done' => 'Finished'
  'pending' => 'Waiting'
  _ => 'Unknown'
}

merge Command

merge combines record fields or combines table rows by position:

let scores = [[name score]; [Mark 19] [Tami 21]]
let colors = [[color flavor]; [yellow vanilla] [blue chocolate]]
$scores | merge $colors

The result has name, score, color, and flavor columns. Mark gets yellow/vanilla and Tami gets blue/chocolate. Use join when matching rows by a key instead of their positions.

move Command

Move columns before or after another column:

ls | move size type --after modified

This places size and then type after modified.

parse Command

parse extracts fields from text, producing a table of matches:

'123 Some St., St. Charles, MO 63304' |
  parse '{street}, {city}, {state} {zip}'

This returns one row with street, city, state, and zip columns. An input with no match produces no rows.

transpose Command

transpose exchanges rows and columns. It is especially useful for converting a record into name/value rows:

{name: Mark, score: 19} | transpose field value

The result has two rows: name/Mark and score/19. For a table, each original row becomes a column.

split column Command

Split a string into columns, optionally specifying column names:

'red,green,blue' | split column ',' first second third

This produces one row with the columns first, second, and third.

to Command

Use to subcommands to serialize structured data. For example:

let scores = [[Name Score]; [Mark 19] [Tami 21]]
$scores | to json --raw
# [{"Name":"Mark","Score":19},{"Name":"Tami","Score":21}]

to json is pretty-printed by default; --raw produces compact output. Other formats include to csv, to html, to md, to toml, to xml, and to yaml. Each format requires an appropriate input shape. For example, a record is suitable for a TOML document, while XML conversion uses a specific tag/attribute/content structure.

Plugins

Plugins add commands to Nushell. They are separate executables and must be compatible with your Nu version. Installing Nu with Cargo does not install the plugins automatically.

For example, to install the query plugin from Cargo (use a compatible --version if your Nu installation is older):

cargo install nu_plugin_query --locked

Then, in Nushell, register the executable:

plugin add ~/.cargo/bin/nu_plugin_query

Adjust the path for your installation; on Windows the executable has an .exe suffix. After registration, load its commands in a separate command:

plugin use query

Registration persists in Nushell’s plugin registry. plugin use makes a registered plugin’s commands available in the current scope. You can put plugin use query in config.nu after registering it so it is available in future interactive sessions. Use plugin list to inspect registered plugins.

Plugin discovery can use the NU_PLUGIN_DIRS constant. It does not use the old TOML plugin_dirs setting. See Plugins for installation details and links to available plugins.

The start command is built in; no nu_plugin_start is needed. For example, start demo.html opens a file using its associated application. The old nu_plugin_chart examples are not part of the current standard plugin set. For frequency bars, use the built-in histogram command described above.

Default Shell

To make Nushell your default shell on Linux or macOS, first locate its executable, for example with which nu. Add the executable’s absolute path to /etc/shells using an editor with administrator privileges, for example sudo vim /etc/shells. Then run chsh -s with that same absolute path. For example, if Homebrew installed Nu there:

chsh -s /opt/homebrew/bin/nu

Use your actual path; Cargo installations commonly use $HOME/.cargo/bin/nu. If using tmux, also review default-shell in ~/.tmux.conf.

Nu is not a POSIX shell and cannot source Bash or Zsh startup files. Translate any environment setup you still need into Nu syntax. See Default Shell.

Scripts

Nushell scripts use the .nu extension. Execute one with nu script.nu. To run it in the current scope and make its definitions available, use source script.nu. Comments begin with #.

Scripts do not automatically load your interactive config.nu. Define or import their dependencies explicitly. A main command can define the script’s command-line parameters:

# Greets the person named on the command line.
def main [name: string] {
  print $"Hello, ($name)!"
}

Save this as greet.nu and run nu greet.nu Mark.

Conditionals use if, else if, and else:

let temperature = 80
if $temperature <= 32 {
  'cold'
} else if $temperature >= 80 {
  'hot'
} else {
  'warm'
}

Use each to transform a sequence or for to perform actions for each item. seq 1 4 produces integers, and 1..4 is an alternative range expression:

1..4 | each {|n| $n | into string } | str join (char newline)

This returns one string containing the numbers on separate lines.

For a numbered report, combine enumerate, each, and str join:

# Formats a list as numbered lines.
def report [values: list<string>] {
  $values | enumerate | each {|entry|
    $"($entry.index + 1)) ($entry.item)"
  } | str join (char newline)
}

let names = [Mark Tami Amanda Jeremy]
report $names
# 1) Mark
# 2) Tami
# 3) Amanda
# 4) Jeremy

For additional examples, see Nu Scripts.

VS Code

The Nushell extension provides support for editing .nu files. Use Nu syntax in configuration files too; they no longer need TOML highlighting.

Comparison to Bash

The following table shows Nu equivalents of some common Bash operations.

BashNushellDescription
man commandhelp commandgets help for a Nu command
$PATH$env.PATHdirectories searched for executables; a list in Nu
cat file.txtopen --raw file.txtreads without extension-based parsing
command > file.txtcommand o> file.txtredirects standard output
command >> file.txtcommand o>> file.txtappends standard output
mkdir -p foo/bar/bazmkdir foo/bar/bazcreates missing parent directories
export NAME=value$env.NAME = 'value'sets an environment variable
cmd1 && cmd2cmd1; cmd2sequences commands; Nu stops on an unhandled error

Nu does not use && and || as shell command separators. A nonzero external exit status is an error under the normal error-handling behavior. Use try/catch to handle errors or complete to inspect an external command’s exit code and captured output explicitly. A command returning the Boolean value false is not itself an error.

For structured data, save is often more convenient than redirection: ls | save listing.json serializes the table as JSON. For a timestamp text file, use date now | into string | save timestamp.txt. See Coming from Bash.

Per Directory Environment Variables

Interactive Nushell supports hooks that run when environment variables change. These hooks do not run in noninteractive scripts. A hook on $env.PWD can update settings when you change directories. The old .nu-env files and autoenv trust command are no longer the mechanism.

For example, add this to config.nu to choose NODE_ENV based on two project directories:

$env.config.hooks.env_change.PWD = (
  $env.config.hooks.env_change.PWD? | default [] | append {|before, after|
    let development = ($env.HOME | path join 'projects' 'airline-reservations')
    let production = ($env.HOME | path join 'projects' 'bank-accounts')
    if $after == $development {
      $env.NODE_ENV = 'development'
    } else if $after == $production {
      $env.NODE_ENV = 'production'
    } else {
      hide-env --ignore-errors NODE_ENV
    }
  }
)

This example takes ownership of NODE_ENV: it sets it for exact directory matches and removes it elsewhere. It does not preserve a previously assigned value or match project subdirectories. The hook runs on directory changes, not just because the configuration was loaded. See Hooks for more details.

For project-specific environment files and restoration when leaving a directory, see the official direnv integration recipe.

Additional Shells

For switching among remembered directories, use the standard library’s directory stack:

use std/dirs

Add the import to config.nu to make these commands available in new sessions.

CommandDescription
dirslists the directory stack and active entry
dirs add pathadds a directory and switches to it
dirs dropremoves the current entry and switches to another
dirs nextswitches to the next entry, wrapping around
dirs prevswitches to the previous entry, wrapping around
dirs goto indexswitches to the entry at a given index

For familiar shell-style names, import the aliases instead:

use std/dirs shells-aliases *

These include shells, enter, n, p, g, and dexit. They manage a directory stack, not separate processes or file-content shells. exit exits the Nu process; it is not the directory-stack removal command. See Directory Stack.

Searching and Completion

Fuzzy completion is supported:

$env.config.completions.algorithm = 'fuzzy'

For filtering structured data or lines of text, try the built-in find, where, str contains, and regex operators. For example, open --raw notes.txt | decode utf-8 | lines | find Nushell. For recursive text searches across files, ripgrep also works as an external command.