# Plugins

Nu can be extended using plugins. Plugins behave much like Nu's built-in commands, with the added benefit that they can be added separately from Nu itself.

::: warning Important
Plugins communicate with Nushell using the `nu-plugin` protocol. This protocol is versioned, and plugins must use the same `nu-plugin` version provided by Nushell.

When updating Nushell, please make sure to also update any plugins that you have registered.
:::

[[toc]]

## Overview

- In order to use a plugin, it needs to be:

  - Installed
  - Added
  - Imported

There are two types of plugins:

- "Core plugins" are officially maintained and are usually installed with Nushell, in the same directory as the Nushell executable.
- Third-party plugins are also available from many sources.

The `$NU_LIB_DIRS` constant or `$env.NU_LIB_DIRS` environment variable can be used to set the search-path for plugins.

### Core Plugin Quickstart

To begin using the Polars plugin:

1. Most package managers will automatically install the core plugins with Nushell. A notable exception, however, is `cargo`. If you installed
   Nushell using `cargo`, see [Installing Core Plugins](#core-plugins) below.

2. (Recommended) Set the plugin search path to include the directory where Nushell and its plugins are installed. Assuming the core plugins are installed
   in the same directory as the Nushell binary, the following can be added to your startup config:

   ```nu
   const NU_PLUGIN_DIRS = [
     ($nu.current-exe | path dirname)
     ...$NU_PLUGIN_DIRS
   ]
   ```

3. Add the plugin to the plugin registry. This only needs to be done one time. The name is the name of the plugin _file_, including its extension:

   ```nu
   # On Unix/Linux platforms:
   plugin add nu_plugin_polars
   # Or on Windows
   plugin add nu_plugin_polars.exe

   plugin list # Confirm it was added to the registry
   ```

   Alternatively, if you did not add the binary directory to the plugin path in Step 2, you can still use an absolute path:

   ```nu
   plugin add ~/.local/share/rust/cargo/bin/nu_plugin_polars
   ```

4. Import the plugin (to begin using it immediately) or restart Nushell. All plugins in the registry are automatically imported when Nushell starts:

   ```nu
   # The name of the plugin, without the leading `nu_plugin` nor any extension
   use polars
   ```

5. Confirm the plugin is working:

   ```nu
   ls | polars into-df | describe
   # => NuDataFrame
   ```

## Installing Plugins

### Core Plugins

Nushell ships with a set of officially maintained plugins which includes:

- `polars`: Extremely fast columnar operations using DataFrames via the [Polars Library](https://github.com/pola-rs/polars). See the [DataFrames Chapter](dataframes.html) for more details.
- `formats`: Support for several additional data formats - EML, ICS, INI, plist, and VCF.
- `gstat`: Returns information on the status of a Git repository as Nushell structured data.
- `query`: Support for querying SQL, XML, JSON, HTML (via selector), and WebPage Metadata
- `inc`: Increment a value or version (e.g., semver). This plugin acts as both an end-user plugin as well as a simple developer example of how to create a plugin.

Nushell also ships with several plugins that serve as examples or tools for plugin developers. These include `nu_plugin_example`, `nu_plugin_custom_values`, and `nu_plugin_stress_internals`.

Core plugins are typically distributed with the Nushell release and should already be installed in the same directory as the Nushell executable. If this is the case on your system, core plugins should be using correct `nu-plugin` protocol version. If your package management system installs them separately, please make sure to update the core plugins whenever Nushell itself is updated.

::: tip Installing using Cargo
For example, when installing or upgrading Nushell directly from crates.io using `cargo install nu --locked`, the corresponding core plugins for that version may also be installed or updated using `cargo install nu_plugin_<plugin_name> --locked`.