Skip to content

Commit a2b857e

Browse files
committed
Update plugins.md (nushell#1258)
More comprehensive plugin installation instructions that should be beneficial especially for newcomers.
1 parent 48ff7c1 commit a2b857e

File tree

1 file changed

+34
-2
lines changed

1 file changed

+34
-2
lines changed

book/plugins.md

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,41 @@ Nu can be extended using plugins. Plugins behave much like Nu's built-in command
44

55
Nu plugins are executables; Nu launches them as needed and communicates with them over [stdin, stdout, and stderr](https://en.wikipedia.org/wiki/Standard_streams). Nu plugins can use either JSON or MSGPACK as their communication encoding.
66

7-
## Adding a plugin
7+
## Downloading and installing a plugin
88

9-
To add a plugin, call the [`register`](/commands/docs/register.md) command to tell Nu where to find it. As you do, you'll need to also tell Nushell what encoding the plugin uses.
9+
::: warning
10+
11+
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.
12+
13+
:::
14+
15+
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.
16+
17+
```nu
18+
> version
19+
```
20+
21+
Find plugins that have the exact same Nushell version either on crates.io, online git repositories or [`awesome-nu`](https://github.com/nushell/awesome-nu/blob/main/plugin_details.md). You can find which version the plugin uses by checking the Cargo.toml file.
22+
23+
To install a plugin by name from crates.io, run:
24+
25+
```nu
26+
> cargo install plugin_name
27+
```
28+
29+
If you chose to download the git repository instead, run this when inside the cloned repository:
30+
31+
```nu
32+
> cargo install --path .
33+
```
34+
35+
This will create a binary file that can be used to register the plugin.
36+
37+
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.
38+
39+
## Registering a plugin
40+
41+
To enable an installed plugin, call the [`register`](/commands/docs/register.md) command to tell Nu where to find it. As you do, you'll need to also tell Nushell what encoding the plugin uses.
1042

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

0 commit comments

Comments
 (0)