Nushell
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
GitHub
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
GitHub
  • Introduction
  • Installation
    • Default Shell
  • Getting Started
    • Quick Tour
    • Moving Around the System
    • Thinking in Nu
    • Nushell Cheat Sheet
  • Nu Fundamentals
    • Types of Data
    • Loading Data
    • Pipelines
    • Working with Strings
    • Working with Lists
    • Working with Records
    • Working with Tables
    • Navigating and Accessing Structured Data
    • Special Variables
  • Programming in Nu
    • Custom Commands
    • Aliases
    • Operators
    • Variables
    • Control Flow
    • Scripts
    • Modules
      • Using Modules
      • Creating Modules
    • Overlays
    • Sorting
    • Testing your Nushell Code
    • Best Practices
  • Nu as a Shell
    • Configuration
    • Environment
    • Stdout, Stderr, and Exit Codes
    • Running System (External) Commands
    • How to Configure 3rd Party Prompts
    • Directory Stack
    • Reedline, Nu's Line Editor
    • Custom Completions
    • Externs
    • Coloring and Theming in Nu
    • Hooks
    • Background Jobs
  • Coming to Nu
    • Coming from Bash
    • Coming from CMD.EXE
    • Nu map from other shells and domain specific languages
    • Nu Map from Imperative Languages
    • Nu Map from Functional Languages
    • Nushell operator map
  • Design Notes
    • How Nushell Code Gets Run
  • (Not So) Advanced
    • Standard Library (Preview)
    • Dataframes
    • Metadata
    • Creating Your Own Errors
    • Parallelism
    • Plugins
    • explore

Types of Data

Traditional Unix shell commands communicate with each other using strings of text -- One command writes text to standard output (often abbreviated stdout) and the other reads text from standard input (or stdin). This allows multiple commands to be combined together to communicate through what is called a "pipeline".

Nushell embraces this approach and expands it to include other types of data in addition to strings.

Like many programming languages, Nu models data using a set of simple, structured data types. Simple data types include integers, floats, strings, and booleans. There are also special types for dates, file sizes, and time durations.

The describe command returns the type of a data value:

42 | describe
# => int

Types at a Glance

TypeExample
Integers-65535
Floats (decimals)9.9999, Infinity
Strings"hole 18", 'hole 18', `hole 18`, hole18, r#'hole18'#
Booleanstrue
Dates2000-01-01
Durations2min + 12sec
File-sizes64mb
Ranges0..4, 0..<5, 0.., ..4
Binary0x[FE FF]
Lists[0 1 'two' 3]
Records{name:"Nushell", lang: "Rust"}
Tables[{x:12, y:15}, {x:8, y:9}], [[x, y]; [12, 15], [8, 9]]
Closures{|e| $e + 1 | into string }, { $in.name.0 | path exists }
Cell-paths$.name.0
Blocksif true { print "hello!" }, loop { print "press ctrl-c to exit" }
Null (Nothing)null
Anylet p: any = 5

Basic Data Types

Integers

Description:Numbers without a fractional component (positive, negative, and 0)
Annotation:int
Literal Syntax:A decimal, hex, octal, or binary numeric value without a decimal place. E.g., -100, 0, 50, +50, 0xff (hex), 0o234 (octal), 0b10101 (binary)
See also:Language Reference - Integer

Simple Example:

10 / 2
# => 5
5 | describe
# => int

Floats/Decimals

Description:Numbers with some fractional component
Annotation:float
Literal Syntax:A decimal numeric value including a decimal place. E.g., 1.5, 2.0, -15.333
See also:Language Reference - Float

Simple Example:

2.5 / 5.0
# => 0.5

Tips

As in most programming languages, decimal values in Nushell are approximate.

10.2 * 5.1
# => 52.01999999999999

Text/Strings

Description:A series of characters that represents text
Annotation:string
Literal Syntax:See Working with strings
See also:Handling Strings
Language Reference - String

As with many languages, Nushell provides multiple ways to specify String values and numerous commands for working with strings.

Simple (obligatory) example:

let audience: string = "World"
$"Hello, ($audience)"
# => Hello, World

Booleans

Description:True or False value
Annotation:bool
Literal Syntax:Either a literal true or false
See also:Language Reference - Boolean

Booleans are commonly the result of a comparison. For example:

let mybool: bool = (2 > 1)
$mybool
# => true
let mybool: bool = ($env.HOME | path exists)
$mybool
# => true

A boolean result is commonly used to control the flow of execution:

let num = -2
if $num < 0 { print "It's negative" }
# => It's negative

Dates

Description:Represents a specific point in time using international standard date-time descriptors
Annotation:datetime
Literal Syntax:See Language Guide - Date

Simple example:

date now
# => Mon, 12 Aug 2024 13:59:22 -0400 (now)
# Format as Unix epoch
date now | format date '%s'
# => 1723485562

Durations

Description:Represent a unit of a passage of time
Annotation:duration
Literal Syntax:See Language Reference - Duration

Durations support fractional values as well as calculations.

Simple example:

3.14day
# => 3day 3hr 21min
30day / 1sec  # How many seconds in 30 days?
# => 2592000

File sizes

Description:Specialized numeric type to represent the size of files or a number of bytes
Annotation:filesize
Literal Syntax:See Language Reference - Filesize

Nushell also has a special type for file sizes.

As with durations, Nushell supports fractional file sizes and calculations:

0.5kB
# => 500 B
1GiB / 1B
# => 1073741824
(1GiB / 1B) == 2 ** 30
# => true

See the Language Reference for a complete list of units and more detail.

Ranges

Description:Describes a range of values from a starting value to an ending value, with an optional stride.
Annotation:range
Literal Syntax:<start_value>..<end_value>. E.g., 1..10.
<start_value>..<second_value>..<end_value>. E.g., 2..4..20
See also:Language Guide - Range

Simple example:

1..5
# => ╭───┬───╮
# => │ 0 │ 1 │
# => │ 1 │ 2 │
# => │ 2 │ 3 │
# => │ 3 │ 4 │
# => │ 4 │ 5 │
# => ╰───┴───╯

Tips

You can also easily create lists of characters with a form similar to ranges with the command seq char as well as with dates using the seq date command.

Cell Paths

Description:An expression that is used to navigated to an inner value in a structured value.
Annotation:cell-path
Literal syntax:A dot-separated list of row (int) and column (string) IDs. E.g., name.4.5.
Optionally, use a leading $. when needed for disambiguation, such as when assigning a cell-path to a variable
See also:Language Reference - Cell-path
Navigating and Accessing Structured Data chapter.

Simple example:

let cp = $.2
# Return list item at index 2
[ foo bar goo glue ] | get $cp
# => goo

Closures

Description:An anonymous function, often called a lambda function, which accepts parameters and closes over (i.e., uses) variables from outside its scope
Annotation:closure
Literal Syntax:{|args| expressions }
See also:Language Reference - Closure

Simple example:

This closure returns a boolean result of the comparison and then uses it in a filter command to return all values greater than 5.

let compare_closure = {|a| $a > 5 }
let original_list = [ 40 -4 0 8 12 16 -16 ]
$original_list | filter $compare_closure
# => ╭───┬────╮
# => │ 0 │ 40 │
# => │ 1 │  8 │
# => │ 2 │ 12 │
# => │ 3 │ 16 │
# => ╰───┴────╯

Closures are a useful way to represent code that can be executed on each row of data via filters

Binary data

Description:Represents binary data
Annotation:binary
Literal Syntax:0x[ffffffff] - hex-based binary representation
0o[1234567] - octal-based binary representation
0b[10101010101] - binary-based binary representation
See also:Language Guide - Binary

Binary data, like the data from an image file, is a group of raw bytes.

Simple example - Confirm that a JPEG file starts with the proper identifier:

open nushell_logo.jpg
| into binary
| first 2
| $in == 0x[ff d8]
# => true

Structured Data Types

Nushell includes a collection of structured data types that can contain the primitive types above. For example, instead of a single float, structured data gives us a way to represent multiple float values, such as a list of temperature readings, in the same value. Nushell supports the following structured data types:

Lists

Description:Ordered sequence of zero or more values of any type
Annotation:list
Literal Syntax:See Language Guide - List
See Also:Working with Lists
Navigating and Accessing Structured Data

Simple example:

[Sam Fred George]
# => ╭───┬────────╮
# => │ 0 │ Sam    │
# => │ 1 │ Fred   │
# => │ 2 │ George │
# => ╰───┴────────╯

Records

Description:Holds key-value pairs which associate string keys with various data values.
Annotation:record
Literal Syntax:See Language Guide - Record
See Also:Working with Records
Navigating and Accessing Structured Data

Simple example:

let my_record = {
  name: "Kylian"
  rank: 99
}
$my_record
# => ╭───────┬────────────╮
# => │ name  │ Kylian     │
# => │ rank  │ 99         │
# => ╰───────┴────────────╯

$my_record | get name
# =>  Kylian

Tables

Description:A two-dimensional container with both columns and rows where each cell can hold any basic or structured data type
Annotation:table
See Also:Working with Tables
Navigating and Accessing Structured Data
Language Guide - Table

The table is a core data structure in Nushell. As you run commands, you'll see that many of them return tables as output. A table has both rows and columns.

Tips

Internally, tables are simply lists of records. This means that any command which extracts or isolates a specific row of a table will produce a record. For example, get 0, when used on a list, extracts the first value. But when used on a table (a list of records), it extracts a record:

[{x:12, y:5}, {x:3, y:6}] | get 0
# => ╭───┬────╮
# => │ x │ 12 │
# => │ y │ 5  │
# => ╰───┴────╯

Other Data Types

Any

Description:When used in a type annotation or signature, matches any type. In other words, a "superset" of other types.
Annotation:any
Literal syntax:N/A - Any literal value can be assigned to an any type
See also:Language Reference - Any

Blocks

Description:A syntactic form used by some Nushell keywords (e.g., if and for)
Annotation:N/A
Literal Syntax:N/A
See also:Language Reference - Block

Simple example:

if true { print "It's true" }

The { print "It's true" } portion above is a block.

Nothing (Null)

Description:The nothing type is to be used to represent the absence of another value.
Annotation:nothing
Literal Syntax:null
See also:Language Reference - Nothing

Simple Example

Using the optional operator ? returns null if the requested cell-path doesn't exist:

let simple_record = { a: 5, b: 10 }
$simple_record.a?
# => 5
$simple_record.c?
# => Nothing is output
$simple_record.c? | describe
# => nothing
$simple_record.c? == null
# => true
Edit this page on GitHub
Contributors: Carson Black, Ibraheem Ahmed, Maximilian Roos, Eoin Kelly, Jonathan Turner, LyesSaadi, JT, sholderbach, Fawad Halim, prrao87, Benjamin Kane, stormasm, Reilly Wood, rgwood, Fernando Herrera, jntrnr, Justin Ma, Aadam Zocolo, merkrafter, merelymyself, Stefan Holderbach, fdncred, Joshua Jolley, Jakub Žádník, Christer Jensen, Dan Davison, Andrey, Leon, Tomochika Hara, Hofer-Julian, Máté FARKAS, Mate Farkas, amtoine, Damian Carrillo, hanjunghyuk, Charles, Trent-Fellbootman, ysthakur, TWSiO, KITAGAWA Yasutaka, Ian Manske, NotTheDr01ds, yo-goto, 0x4D5352, joshuanussbaum
Next
Loading Data