Introducing npm: A Nushell Package Manager

Today I’m happy to introduce npm, a package manager for Nushell.

Using npm

To use an npm package with your Nushell script, simply type npm install <package-name> in your Nushell terminal. This will download the package and make it available for use in your scripts. Then, type use node_modules/<package-name> in your Nushell script to load the package.

To publish your Nushell package on npm, create a package.json file in your Nushell script directory. This file should contain metadata for your package, including the name, version, and description. You can then run npm publish to publish your package to npm. Your package should include a mod.nu file at the top level so that someone can simply run use node_modules/<package-name> to load your package.

If you create a plugin, be sure to put the binary in the bin section of the package.json file, like this:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A Nushell plugin",
  "bin": {
    "my-plugin": "./bin/my-plugin"
  }
}

Someone can then run plugin add node_modules/.bin/my-plugin to install your plugin. After that, they can run plugin use my-plugin to use it.

That’s it!

Why?

When researching package managers for Nushell, I quickly discovered the following facts:

• nupm is unfinished and actively discourages its own use.
• Cargo puts packages in an unpredictable, hash-based directory, incompatible with the constant-folder requirements of Nushell.
• pip and uv would technically work but come with a convention of loading a special virtual environment, which is undesirable for maximum developer experience.
• GitHub is not a package manager, and GitHub-based package management requires having the entire commit history of all dependencies, and all dependencies of those dependencies, which is extremely undesirable for use in production apps.
• Most system package managers, like brew, are not permissionless, and you can’t just upload your script to them.

Meanwhile, npm, the package manager for Node.js, satisfies every constraint:

• Packages are placed inside a node_modules directory, making it possible to load them by simply writing use node_modules/<package-name>.
• It supports Nushell scripts and any other files you might want to include.
• There is a large community of alternative package managers based on npm, such as pnpm and yarn, which provide many options for installing packages quickly and ensuring precise versions.
• npm is permissionless in the sense that anyone can publish a package at any time without needing to go through a gatekeeper.

Introducing npm

That’s why today I’m happy to announce npm, a Nushell package manager that is 100% compatible with npm, the “Not a Package Manager” for Node.js.

You might be wondering whether npm conflicts with npm. However, I have designed npm from day one so that it is 100% compatible with npm. Everything about it is exactly the same, including the API, code, domain name, and even the name. It is so compatible, that I didn’t even have to write any code: I just started using it right away!

Conclusion

npm is a package manager that runs on every platform and has been backfilled with millions and millions of packages. It already works, and it is already 100% compatible with Nushell. You can use it right now.

npm is currently in alpha, but I expect the full release to come as early as fifteen years ago.