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.

Nu plugins are executables; Nu launches them as needed and communicates with them over stdin, stdout, and stderropen in new window. Nu plugins can use either JSON or MSGPACK as their communication encoding.

Downloading and installing a plugin

WARNING

Please note that plugin installation methods are still under heavy development and that the following workflow will be refined before the release of 1.0. The nupm official package manager should simplify installation in the future when it becomes ready for general use.

To install a plugin on your system, you first need to make sure that the plugin uses the same version of Nu as your system.

> version

Find plugins that have the exact same Nushell version either on crates.io, online git repositories or awesome-nuopen in new window. You can find which version the plugin uses by checking the Cargo.toml file.

To install a plugin by name from crates.io, run:

> cargo install plugin_name

If you chose to download the git repository instead, run this when inside the cloned repository:

> cargo install --path .

This will create a binary file that can be used to register the plugin.

Keep in mind that when installing using crates.io, the binary can be saved in different locations depending on how your system is set up. A typical location is in the users's home directory under .cargo/bin.

Registering a plugin

To enable an installed plugin, call the register command to tell Nu where to find it. As you do, you'll need to also tell Nushell what encoding the plugin uses.

Please note that the plugin name needs to start with nu_plugin_, Nu uses the name prefix to detect plugins.

Linux+macOS:

> register ./my_plugins/nu_plugin_cool

Windows:

> register .\my_plugins\nu_plugin_cool.exe

When register is called:

  1. Nu launches the plugin, and waits for the plugin to tell Nu which communication encoding it should use
  2. Nu sends it a "Signature" message over stdin
  3. The plugin responds via stdout with a message containing its signature (name, description, arguments, flags, and more)
  4. Nu saves the plugin signature in the file at $nu.plugin-path, so registration is persisted across multiple launches

Once registered, the plugin is available as part of your set of commands:

> help commands | where command_type == "plugin"

Updating a plugin

When updating a plugin, it is important to run register again just as above to load the new signatures from the plugin and allow Nu to rewrite them to the plugin file ($nu.plugin-path).

Managing plugins

To view the list of plugins you have installed:

> plugin list
╭───┬─────────┬────────────┬─────────┬───────────────────────┬───────┬───────────────────────────────╮
 # │  name   │ is_running │   pid   │       filename        │ shell │           commands            │
├───┼─────────┼────────────┼─────────┼───────────────────────┼───────┼───────────────────────────────┤
 0  gstat    true        1389890  .../nu_plugin_gstat           ╭───┬───────╮                 
                                                                 0  gstat                  
                                                                ╰───┴───────╯                 
 1  inc      false                .../nu_plugin_inc             ╭───┬─────╮                   
                                                                 0  inc                    
                                                                ╰───┴─────╯                   
 2  example  false                .../nu_plugin_example         ╭───┬───────────────────────╮ 
                                                                 0  nu-example-1           
                                                                 1  nu-example-2           
                                                                 2  nu-example-3           
                                                                 3  nu-example-config      
                                                                 4  nu-example-disable-gc  
                                                                ╰───┴───────────────────────╯ 
╰───┴─────────┴────────────┴─────────┴───────────────────────┴───────┴───────────────────────────────╯

Plugins stay running while they are in use, and are automatically stopped by default after a period of time of inactivity. This behavior is managed by the plugin garbage collector. To manually stop a plugin:

> plugin stop gstat

If we check plugin list again, we can see that it is no longer running:

> plugin list | where name == gstat | select name is_running
╭───┬───────┬────────────╮
 # │ name  │ is_running │
├───┼───────┼────────────┤
 0  gstat  false      
╰───┴───────┴────────────╯

Plugin garbage collector

Nu comes with a plugin garbage collector, which automatically stops plugins that are not actively in use after a period of time (by default, 10 seconds). This behavior is fully configurable:

$env.config.plugin_gc = {
    # Settings for plugins not otherwise specified:
    default: {
        enabled: true # set to false to never automatically stop plugins
        stop_after: 10sec # how long to wait after the plugin is inactive before stopping it
    }
    # Settings for specific plugins, by plugin name
    # (i.e. what you see in `plugin list`):
    plugins: {
        gstat: {
            stop_after: 1min
        }
        inc: {
            stop_after: 0sec # stop as soon as possible
        }
        stream_example: {
            enabled: false # never stop automatically
        }
    }
}

For more information on exactly under what circumstances a plugin is considered to be active, see the relevant section in the contributor book.

Removing a plugin

To remove a plugin, edit the $nu.plugin-path file and remove all of the register commands referencing the plugin you want to remove, including the signature argument.

Examples

Nu's main repo contains example plugins that are useful for learning how the plugin protocol works:

Debugging

The simplest way to debug a plugin is to print to stderr; plugins' standard error streams are redirected through Nu and displayed to the user.

Help

Nu's plugin documentation is a work in progress. If you're unsure about something, the #plugins channel on the Nu Discordopen in new window is a great place to ask questions!

More details

The plugin chapter in the contributor book offers more details on the intricacies of how plugins work from a software developer point of view.

Contributors: Reilly Wood, Justin Ma, WindSoilder, Devyn Cairns, Hofer-Julian, Hugo Sena Ribeiro, Ibraheem Ahmed, JT, John Smith, Michael, Michael Angerman, TornaxO7, jweckman, nalpine, petrisch