Standard Library

Nushell ships with a standard library of useful commands written in native Nu. By default, the standard library is loaded into memory (but not automatically imported) when Nushell starts. The exception is the small std/prelude module, which is imported automatically and provides the banner and pwd commands.

Overview

The standard library currently includes:

• Assertions
• An alternative help system with support for completions.
• Additional JSON variant formats
• XML Access
• Logging
• And more

To see a complete list of the commands available in the standard library, run the following:

nu -c "
  use std
  scope commands
  | where name =~ '^std '
  | select name description extra_description
  | wrap 'Standard Library Commands'
  | table -e
"

Importing the Standard Library

The Standard Library modules and submodules are imported with the use command, just as any other module. See Using Modules for more information.

While working at the commandline, it can be convenient to load the entire standard library using:

use std *

However, this form should be avoided in custom commands and scripts since it has the longest load time.

Importing Submodules

Each submodule of the standard library can be loaded separately. Again, for best performance, load only the submodule(s) that you need in your code.

See Importing Modules for general information on using modules. The recommended import for each of the Standard Library submodules is listed below:

1. Submodules with <command> <subcommand> form

These submodules are normally imported with use std/<submodule> (without a glob/*):

• use std/assert: assert and its subcommands
• use std/bench: The benchmarking command bench
• use std/clip: clip copy52 and clip paste52, which copy to and paste from the system clipboard through the terminal (OSC 52), and clip prefix, which adds a prefix to each line of the content to be copied
• use std/config: config dark-theme and config light-theme (themes for $env.config.color_config) and config env-conversions
• use std/dirs: The directory stack command dirs and its subcommands
• use std/input: The input display command
• use std/help: An alternative version of the help command and its subcommands which supports completion and other features
• use std/iter: Additional iter-prefixed iteration commands, such as iter find and iter scan
• use std/log: The log <subcommands> such as log warning <msg>
• use std/math: Mathematical constants such as $math.E. These can also be imported as definitions as in Form #2 below.
• use std/random: The random dice command

2. Import the definitions (contents) of the module directly

Some submodules are easier to use when their definitions (commands, aliases, constants, etc.) are loaded into the current scope. For instance:

use std/formats *
ls | to jsonl

Submodules that are normally imported with use std/<submodule> * (with a glob/*):

• use std/dt *: Additional commands for working with datetime values
• use std/formats *: Additional to and from format conversions
• use std/math *: The math constants without a prefix, such as $E. Note that the prefixed form #1 above is likely more understandable when reading and maintaining code.
• use std/testing *: The @test, @ignore, @before-each, @before-all, @after-each, and @after-all attributes for marking tests
• use std/util *: Miscellaneous commands such as path add, repeat, null-device, and structure
• use std/xml *: Additional commands for working with XML data

3. use std <submodule>

It is possible to import Standard Library submodules using a space-separated form:

use std formats *

The Standard Library Candidate Module

std-rfc, found in the nushell Repository, serves as a staging ground for possible Standard Library additions.

std-rfc ships with Nushell, so its submodules can be imported the same way as the Standard Library's, for example use std-rfc/str. It currently includes the conversions, date, iter, kv, path, pb, random, str, tables, url, and xml submodules.

If you are interested in adding to the Standard Library, please submit your code via PR to the std-rfc module in that repository. We also encourage you to try these candidate commands and provide feedback on them.

Disabling the Standard Library

To disable the standard library, you can start Nushell using:

nu --no-std-lib

This can be especially useful to minimize overhead when running a command in a subshell using nu -c. With -c, $nu.startup-time shows how long Nushell took to start before running the command, so you can compare the two:

nu --no-std-lib -n -c "$nu.startup-time"
# => 9ms 650µs 250ns

nu -n -c "$nu.startup-time"
# => 11ms 558µs 83ns

You will not be able to import the library, any of its submodules, nor use any of its commands, when it is disabled in this way. This includes the banner and pwd commands from std/prelude.

Using std/log in Modules

Optimal Startup

If Nushell's startup time is important to your workflow, review your startup configuration in config.nu, env.nu, and potentially others for inefficient use of the standard library. The following command should identify any problem areas:

view files
| enumerate | flatten
| where filename !~ '^std'
| where filename !~ '^repl_entry'
| where {|file|
    (view span $file.start $file.end) =~ 'use\s+std(\s|;|$)'
  }

Edit those files to use the recommended syntax in the Importing Submodules section above.