nushell

nushell
is a new type of shell. It has native support for structured and typed data, such as arrays, tables, records, numeric/boolean types, etc., and offers syntax and built-ins that make it easy to query, filter, sort, transform, convert, and otherwise manipulate various data types in a shell-like workflow, and supports taking input and producing output in many builtin or user-defined formats.
Installation
Install
the
nushell
package. You can then start
nushell
:
$ nu
Features
Structured data support
Built-ins in
nushell
understand and output complex data types. For example, the
ls
builtin outputs an array of items representing files, which have attributes like
name
,
size
,
type
(
file
,
dir
,
symlink
, etc.),
modified
, etc.
In addition, many built-ins are offered for querying and manipulating data, as data - not as text like in traditional shell, while still having a shell-like workflow. For example, the
where
builtin can filter the contents of an array or table:
> ls | where type == file | where size > 10mb
Since it filters data received via its "stdin" and produces it via its "stdout", multiple filters can be chained like above. Another example:
> ls | where type == file | get size | math sum
The
get
builtin can be used access an attribute from an object. In this example, we are feeding it an array of objects via stdin, so it fetches the
size
property of each element in the array, which produces an array of numeric values. Finally, we feed that array to
math sum
which calculates their sum.
Output
nushell
has versatile output features. Right out of the box, it boasts a modern look with colors, ASCII art, and detailed error messages.
Output as text
By default, the output of commands like
ls
(which as we said produces an array of structured objects) is displayed as a colored text table with enumerated rows, where each file is a row and each attribute is a column. Example:
/usr/lib> ls | where name =~ "alsa|pulse|pipewire" | first 10
╭───┬────────────────────────────┬─────────┬──────────┬──────────────╮
│ # │            name            │  type   │   size   │   modified   │
├───┼────────────────────────────┼─────────┼──────────┼──────────────┤
│ 0 │ alsa-lib                   │ dir     │   4.1 KB │ 2 days ago   │
│ 1 │ alsa-topology              │ dir     │   4.1 KB │ 3 months ago │
│ 2 │ libdrumstick-alsa.so       │ symlink │     22 B │ 7 months ago │
│ 3 │ libdrumstick-alsa.so.2     │ symlink │     26 B │ 7 months ago │
│ 4 │ libdrumstick-alsa.so.2.7.2 │ file    │ 335.3 KB │ 7 months ago │
│ 5 │ libgvncpulse-1.0.so        │ symlink │     21 B │ 9 months ago │
│ 6 │ libgvncpulse-1.0.so.0      │ symlink │     25 B │ 9 months ago │
│ 7 │ libgvncpulse-1.0.so.0.0.1  │ file    │  14.1 KB │ 9 months ago │
│ 8 │ libpipewire-0.3.so         │ symlink │     20 B │ 2 weeks ago  │
│ 9 │ libpipewire-0.3.so.0       │ symlink │     26 B │ 2 weeks ago  │
╰───┴────────────────────────────┴─────────┴──────────┴──────────────╯
Behavior depends on configuration.
> $env.config.hooks.display_output
if (term size).columns >= 100 { table -e } else { table }
Output in data formats
Data can also be output in any various data formats, including JSON, YAML, TOML, HTML, XML, SQL, CSV, Markdown tables, and others. The user can also define their own custom viewers to support arbitrary data types.
To output data in a given format, simply pipe the data to
to
FORMAT
:
/usr/lib> ls | where name =~ alsa | first 3 | to yaml
- name: alsa-lib
  type: dir
  size: 4096
  modified: 2023-05-03 16:04:35.544273606
- name: alsa-topology
  type: dir
  size: 4096
  modified: 2023-01-13 19:29:45.179245376
- name: libdrumstick-alsa.so
  type: symlink
  size: 22
  modified: 2022-10-02 13:28:57
To save the output of a command in a file, pipe it to the
save
builtin:
> ls | to json | save my-file.json
If the output file already exists,
save
will refuse to overwrite it. You can force overwriting files using the
-f
switch.
Note that
nushell
defaults to producing pretty-printed JSON. To output JSON without pretty-printing, use
to json --raw
.
See
to --help
for a list of supported formats.
Error output
nushell
prints colorized and detailed error messages that pinpoint the exact source of the error and suggest solutions. Example error message:
> ls -a --never-gonna-give-you-up /tmp
Error: nu::parser::unknown_flag

  × The `ls` command doesn't have flag `never-gonna-give-you-up`.
   ╭─[entry #1:1:8]
 1 │  ls -a --never-gonna-give-you-up /tmp
   ·        ────────────┬────────────
   ·                    ╰── unknown flag
   ╰────
  help: Use `--help` to see available flags
Input
Input from data files
nushell
has native support for reading data in various formats, including JSON, YAML, TOML, SQL, HTML/XML, and others, allowing the user to utilize its powerful data querying and manipulation capabilities on data read from any file format. The user can also add support for new formats by adding plugins.
Data is read from files using the
open
builtin. For example, assuming the following file
movies.yaml
- movie: Matrix
  genre: Action
- movie: Lord of the Rings
  genre: [Action, Fantasy]
- movie: Independence Day
  genre: [Action, Sci-Fi]
Using
open
would produce the following:
> open movies.yaml
╭───┬───────────────────┬─────────────────╮
│ # │       movie       │      genre      │
├───┼───────────────────┼─────────────────┤
│ 0 │ Matrix            │ Action          │
│ 1 │ Lord of the Rings │ ╭───┬─────────╮ │
│   │                   │ │ 0 │ Action  │ │
│   │                   │ │ 1 │ Fantasy │ │
│   │                   │ ╰───┴─────────╯ │
│ 2 │ Independence Day  │ ╭───┬────────╮  │
│   │                   │ │ 0 │ Action │  │
│   │                   │ │ 1 │ Sci-Fi │  │
│   │                   │ ╰───┴────────╯  │
╰───┴───────────────────┴─────────────────╯
Input from external programs
For external programs, which typically produce their output as plain text,
nushell
offers the ability to parse their output and convert it into a structured datatype, so that the user can utilize
nushell
's full native data processing capabilities even on arbitrary output generated by agnostic programs.
Using parse with regular expression
Parsing external program output can be easily performed using the
parse
builtin. One typical workflow is using the
-r
switch, which tells
parse
to use a
regular expression
for extracting fields out of each line of text in the input. For example, to parse the output of
pacman
's
-Si
command
, one might do something like this:
> pacman -Si rclone | parse -r '(?P<name>.*\w) +: (?P<value>.+)'
╭────┬────────────────┬─────────────────────────────────────────╮
│  # │      name      │                  value                  │
├────┼────────────────┼─────────────────────────────────────────┤
│  0 │ Repository     │ extra                                   │
│  1 │ Name           │ rclone                                  │
│  2 │ Version        │ 1.72.1-1                                │
│  3 │ Description    │ rsync for cloud storage                 │
│  4 │ Architecture   │ x86_64                                  │
│  5 │ URL            │ https://github.com/rclone/rclone        │
│  6 │ Licenses       │ MIT                                     │
│  7 │ Groups         │ None                                    │
│  8 │ Provides       │ None                                    │
│  9 │ Depends On     │ glibc                                   │
│ 10 │ Optional Deps  │ fuse3: for rclone mount                 │
│ 11 │ Conflicts With │ None                                    │
│ 12 │ Replaces       │ None                                    │
│ 13 │ Download Size  │ 25.99 MiB                               │
│ 14 │ Installed Size │ 98.07 MiB                               │
│ 15 │ Packager       │ T.J. Townsend <blakkheim@archlinux.org> │
│ 16 │ Build Date     │ Wed Dec 10 18:03:32 2025                │
│ 17 │ Validated By   │ SHA-256 Sum  Signature                  │
╰────┴────────────────┴─────────────────────────────────────────╯
nushell
uses a Perl-like regular expression syntax, which is provided by the
Regex crate
(of the
Rust
programming language). The syntax is described in the
crate's documentation
.
Using parse with template string
Another way, which does not require regular expression knowledge, is by omitting the
-r
switch and providing
parse
with a template string. However, depending on the case, it may necessitate extra steps for pre- and post-processsing the results. For example:
> pacman -Si just | lines | parse '{field} : {value}' | str trim
Here we performed the same task as the above, but with three differences. Aside from using a template string rather than regular expression (i.e. without the
-r
switch), the first notable difference is that when
parse
is given a template strings, it acts on the entirety of its input rather than on each line in it. So in order to parse the input on a per-line basis, we must first split it into an array of lines using the
lines
builtin.
The second difference is that template strings do not automatically trim surplus whitespace, which results in the matched fields containing all extra whitespace surrounding them, so we had to post-process the output with
str trim
, which conveniently acts on all fields for all items in the provided array.
Data manipulation
Conversion
The combination of its
open
and
save
builtins allow it to be easily used to convert data files across any supported formats. For example:
The data can then be freely manipulated or converted by piping it to other commands. For example:
> open movies.yaml | first 2 | to json --raw
[{"movie":"Matrix","genre":"Action"},{"movie":"Lord of the Rings","genre":["Action","Fantasy"]}]
> open movies.yaml | first 2 | to json --raw | save movies.json
> cat movies.json
(same output as above)
Comparison with traditional shells
This article or section needs expansion.
Reason:
Needs to elaborate on some of the points enumerated in the first paragraph. (Discuss in
Talk:Nushell
)
nushell
is not a POSIX shell, and has significant differences from traditional/POSIX-compatible shells in various ways, including its syntax, supported builtins, the way builtins work, the command-line options they accept, the type of data they consume and produce, and so on.
Syntax
Redirecting output to a file cannot be done using
>
like in other shells (as it has greater-than meaning).
So rather than:
ls > file.txt
which is an error, use e.g.:
ls | get name | save file.txt
Nushell's redirection syntax is e.g.
out>
(abbreviated as
o>
),
err>
,
e+o>
.
It can be used directly in the former example above, if system's
ls
command instead of internal one is used, by prefixing with
^
:
^ls o> file.txt
See also
nushell
's Project Homepage
.
Nushell's Introductory Book
, which goes in detail about its features and facets.
Nushell's Command Reference
Nushell's Cookbook
, containing examples about how to perform tasks from various categories in
nushell
.