Nushell's status note promises a daily driver and warns about instability in one paragraph

Three sentences, three confidence levels, in the status paragraph

The Status section is three sentences and they do not agree with each other in tone. This project has reached a minimum-viable-product level of quality. Many people use it as their daily driver, but it may be unstable for some commands. Nu's design is subject to change as it matures.

The first sentence is a quality claim with a specific, modest bar in it. The second is a usage report paired with a warning, which is the most useful sentence in the file because it is the one you can check against your own experience. The third is a promise that things will change.

The version number does not contradict any of it, and that is the point. The manifest is at 0.116.0, still below 1.0, so nothing in the numbering backs a stability promise either.

The consequence for you is a precise statement of the exposure. The file authorizes using it as a daily driver, and in the same breath tells you some commands are unstable and the design will move. What you own is the configuration and any scripts layered on top, not the shell.

The worked example prints 0.72.0 while the manifest says 0.116.0

The opening files section is the best demonstration of the structured data model, and it ends on a number that is out of date. The example is a three-step drill:

open Cargo.toml
open Cargo.toml | get package
open Cargo.toml | get package.version

and the last of those returns 0.72.0.

The manifest in this repository declares version 0.116.0. So the punchline of the flagship example, the moment where a file is opened, drilled into and reduced to a single scalar, prints a value from an older release line.

Half of that same output is still current, which makes it more interesting rather than less. The description field in the example reads A new type of shell, and that is exactly what the manifest says today.

The consequence is small in practice and worth knowing anyway. A reader who runs the third line against their own checkout will get a different number than the file promised, and has no way to tell from the file whether the shell is wrong or the documentation is. That is a reasonable first suspicion about any documentation example, but here it is in the section the file uses to make its central argument.

Installation is two one-liners, and platform support is a file in the repository

The whole quick install is:

# Linux and macOS
brew install nushell
# Windows
winget install nushell

Two commands, and the first one sends Linux and macOS to the same place. Homebrew is a macOS package manager that is unusual on Linux distributions, so a Linux user following the line literally ends up installing a macOS-oriented toolchain. winget covers Windows.

Everything else is a pointer. There is a setup action for using Nu in GitHub Actions, a link to the installation chapter of the book, a badge for the many package managers Nu is available through, and then the sentence that actually answers the question people have, which is to see the platform support policy for details about which platforms the team actively supports.

That policy lives at devdocs/PLATFORM_SUPPORT.md inside the repository, and it is the only statement in the README about what is supported where.

The consequence is that the file treats its own support matrix as a moving document rather than a claim, which is honest, and it puts the answer one repository browse away from the question. Reading it before you install is cheap.

Eight plugins ship in the workspace as separate binaries

Plugins follow the same structured data model as the built-in commands, and the README points at the `crates/nu_plugins_*` directories for examples. Counting the workspace members with that prefix gives eight: custom values, example, formats, gstat, inc, polars, query, and stress internals.

Two of those names carry the weight. A dataframe engine and a SQL engine are plugins rather than built-in commands, which is a deliberate line the project drew about what belongs in the core.

The structural consequence is that a plugin is a separate binary, so it is a process boundary. A plugin that is not running cannot contribute, and every value that crosses that boundary is serialized into the structured data model rather than passed as a reference. The data model is what makes the boundary survivable, and the same model is the compatibility contract between a plugin and whatever version of the shell it was built against.

So the answer to how hard a plugin is has two parts, and the file only really develops the first. The shape of the data crossing the process boundary is well specified by the built-in command behaviour. How a plugin is discovered, started and version-matched is where you will be reading the tree rather than the README.

The test suite turns off Cargo's harness and supplies its own entry point

The manifest does two things to the test setup that are worth pausing on. It sets `autotests = false`, which tells Cargo not to look for tests in the conventional places. And it declares a single explicit test target:

[[test]]
name = "tests"
path = "tests/main.rs"
harness = false

That is one test binary, at one path, with the standard harness turned off. Everything Cargo normally gives you for free, output formatting, name filtering, parallelism, per-test reporting, has to be reimplemented by whatever runs at tests/main.rs.

For a shell this is understandable rather than odd. The tests are themselves Nushell programs, and asserting on a shell means running pipelines, capturing rendered tables and comparing output, which is not the shape the default harness is built for. A `tests/` directory at the top level and the custom entry point are two halves of the same decision.

The consequence is for contributors rather than users. The file documents no test command at all, so a new contributor has to read the manifest to learn that the suite is invoked through one binary with a custom runner, and that the usual `cargo test` discovery will find nothing.

The version number is written three times and only one of them is inherited

The manifest declares the version once, in the workspace package table, and the package table inherits it. Then the Windows resource metadata repeats it literally, twice:

[package.metadata.winresource]
FileVersion = "0.116.0"
ProductVersion = "0.116.0"

So there is one authoritative value and two copies. The copyright line in the same block spans 2019 to 2026, and the product name is Nushell while the file description is A new type of shell.

Packaging is configured alongside it, for the binstall installer, with a download URL template built from repository, version, name and target, a default archive format of tgz, and an override that switches to zip for the x86_64-pc-windows-msvc target. There is a wix/ directory for the Windows installer and a Cross.toml for cross-compilation.

The consequence is a release checklist item that is easy to miss and easy to detect. A release that bumps the workspace version and forgets the winresource block produces a Windows binary whose embedded file version lags its own tag, and a user reading file properties sees a version that does not match what they downloaded. The two archive formats are per target, so any download script that assumes one format breaks on Windows MSVC.

The configuration you get is the sample_config directory, copied on first start

There is no configuration file in this repository. There is a directory of them, at crates/nu-config/default_files, and the file describes it as the set you get when you start Nushell for the first time. It sets all of the default configuration, and from there you customize it for your own needs.

To find where yours actually is, the file gives one command:

$nu.config-path

That is the entire configuration story in the README. No key names, no environment variable names, no precedence rules between a config file, an environment variable and a command line flag.

The absence is defensible, because the book has a configuration chapter and the file says so. It also means the first thing you do after installing is discover a file that already exists on disk and start reading it, which is a reasonable way to learn a shell and a slow way to answer a specific question.

The consequence is that anyone coming to Nushell with a particular setting in mind, an alias, a keybinding, a prompt, a PATH rule, has to go to the book. What the file does give you is the honest fact that the defaults are a real file you can read, rather than something compiled in and undiscoverable.

Editorial conclusion

Use Nushell as your interactive shell if you want structured pipelines and a config you can read as Nu rather than as shell, and if you are willing to treat your own configuration and any scripts you write as the thing that breaks first. Do not adopt it expecting POSIX compatibility, because the file never claims it, and do not read the daily driver sentence as a stability guarantee, because the same paragraph says some commands may be unstable and that the design is subject to change, and the version is still 0.x. Before you install, check devdocs/PLATFORM_SUPPORT.md for whether your platform is actively supported, since the quick install line sends Linux and macOS to the same package manager. And if you plan to write plugins, remember that eight of them ship in the workspace as separate binaries, so the process boundary, not the data model, is the first thing to get right.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes