# Using Modules

[[toc]]

## 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`](/commands/docs/use.md) command:

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

For example:

```nu
use std/log
log info "Hello, Modules"
```

::: tip
The example above uses the [Standard Library](../standard_library.md), 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 Modules

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`](/commands/docs/use.md) 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:

  ::: details Example

  ```nu
  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:

  ::: details Example

  ```nu
  # 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 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.

  ::: details Example

  ```nu
  use ~/nushell/modules/std-rfc/bulk-rename.nu
  # Or
  cd ~/nushell/modules
  use std-rfc/bulk-rename.nu
  ```

  :::

- A virtual directory:

  ::: details 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.

  ```nu
  use std/assert
  assert equal 'string1' "string1"
  ```

  :::

- Less commonly, the name of a module already created with the [`module`](/commands/docs/module.md) 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](./creating_modules.md#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](../standard_library.md#importing-submodules) 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:

  ```nu
  use std/log