Using Modules

Overview

End-users can add new functionality to Nushell by using ("importing") modules written by others.

To import a module and its definitions, we call the use command:

use <path/to/module> <members...>

For example:

use std/log
log info "Hello, Modules"

Tips

The example above uses the Standard Library, a collection of modules built-in to Nushell. Because it is readily available to all Nushell users, we'll also use it for several of the examples below.

Installing a module is simply a matter of placing its files in a directory. This might be done via git clone (or other version control system), a package manager such as nupm, or manually. The module's documentation should provide recommendations.

Importing Modules

Anything after the use keyword forms an import pattern which controls how the definitions are imported.

Notice above that use has two arguments:

A path to the module
(Optional) The definitions to import

The module's documentation will usually tell you the recommended way to import it. However, it can still be useful to understand the options available:

Module Path

The path to the module can be:

An absolute path to a directory containing a mod.nu file:
Example
```
use ~/nushell/modules/nupm
```
Note that the module name (i.e., its directory) can end in a / (or \ on Windows), but as with most commands that take paths (e.g., cd), this is completely optional.
A relative path to a directory containing a mod.nu file:
Example
```
# cd then use the mod.nu in the relative nupm directory
cd ~/nushell/modules
use nupm
# or
use nupm/
```
Note that the module name (its directory) can end in a / (or \ on Windows), but as with most commands that take a paths (e.g., cd), this is completely optional.
Important! Importing modules from $env.NU_LIB_DIRS
When importing a module via a relative path, Nushell first searches from the current directory. If a matching module is not found at that location, Nushell then searches each directory in the $env.NU_LIB_DIRS list.
This allows you to install modules to a location that is easily accessible via a relative path regardless of the current directory.
An absolute or relative path to a Nushell module file. As above, Nushell will search the $env.NU_LIB_DIRS for a matching relative path.
Example
```
use ~/nushell/modules/std-rfc/bulk-rename.nu
# Or
cd ~/nushell/modules
use std-rfc/bulk-rename.nu
```
A virtual directory:
Example
The standard library modules mentioned above are stored in a virtual filesystem with a std directory. Consider this an alternate form of the "absolute path" examples above.
```
use std/assert
assert equal 'string1' "string1"
```
Less commonly, the name of a module already created with the module command. While it is possible to use this command to create a module at the commandline, this isn't common or useful. Instead, this form is primarily used by module authors to define a submodule. See Creating Modules - Submodules.

Module Definitions

The second argument to the use command is an optional list of the definitions to import. Again, the module documentation should provide recommendations. For example, the Standard Library Chapter covers the recommended imports for each submodule.

Of course, you always have the option to choose a form that works best for your use-case.

Import an entire module/submodule as a command with subcommands
In an earlier example above, we imported the std/log module without specifying the definitions:
```
use std/log
log info "Hello, std/log Module"
```
Notice that this imports the log submodule with all of its subcommands (e.g., log info, log error, etc.) into the current scope.
Compare the above to the next version, where the command becomes std log info:
```
use std
std log info "Hello, std Module"
```
Import all of the definitions from a module
Alternatively, you can import the definitions themselves into the current scope. For example:
```
use std/formats *
ls | to jsonl
```
Notice how the to jsonl command is placed directly in the current scope, rather than being a subcommand of formats.
Import one or more definitions from a module
Nushell can also selectively import a subset of the definitions of a module. For example:
```
use std/math PI
let circle = 2 * $PI * $radius
```
Keep in mind that the definitions can be:
- Commands
- Aliases
- Constants
- Externs
- Other modules (as submodules)
- Environment variables (always imported)
Less commonly, a list of imports can also be used:
```
use std/formats [ 'from ndjson' 'to ndjson' ]
```
Importing submodules
While you can import a submodule by itself using use <module> </submodule> (e.g., use std help), the entire parent module and all of its definitions (and thus submodules) will be parsed when using this form. When possible, loading the submodule as a module will result in faster code. For example:
```
# Faster
use std/help
```

Importing Constants

As seen above with the std/math examples, some modules may export constant definitions. When importing the entire module, constants can be accessed through a record with the same name as the module:

# Importing entire module - Record access
use std/math
$math.PI
# => 3.141592653589793

$math
# => ╭───────┬──────╮
# => │ GAMMA │ 0.58 │
# => │ E     │ 2.72 │
# => │ PI    │ 3.14 │
# => │ TAU   │ 6.28 │
# => │ PHI   │ 1.62 │
# => ╰───────┴──────╯

# Or importing all of the module's members
use std/math *
$PI
# => 3.141592653589793

Hiding

Any custom command or alias, whether imported from a module or not, can be "hidden" to restore the previous definition using the hide command.

The hide command also accepts import patterns, similar to use, but interprets them slightly differently. These patterns can be one of the following:

If the name is a custom command, the hide command hides it directly.
If the name is a module name, it hides all of its exports prefixed with the module name

For example, using std/assert:

use std/assert
assert equal 1 2
# => Assertion failed
assert true
# => Assertion passes

hide assert
assert equal 1 1
# => Error:
# => help: A command with that name exists in module `assert`. Try importing it with `use`

assert true
# => Error:
# => help: A command with that name exists in module `assert`. Try importing it with `use`

Just as you can use a subset of the module's definitions, you can also hide them selectively as well:

use std/assert
hide assert main
assert equal 1 1
# => assertion passes

assert true
# => Error:
# => help: A command with that name exists in module `assert`. Try importing it with `use`