Guide · Open source
How to use Nushell: install, pipelines and config basics
Updated · written with AI from the project's own documentation and checked against our catalogue data
Nushell (nu) is a command-line shell, the program you type commands into in a terminal. Unlike shells that pass plain text between commands, it passes structured data such as tables and records, so a command like ls returns rows you can filter and sort. This guide shows you how to install it, run pipelines, load files as data and find your config file.
Nushellnushell/nushell · ★ 40.8k · MIT Install options & downloads Quick start
- 1Install Nushell. Run brew install nushell on Linux or macOS, or winget install nushell on Windows.
- 2Start nu. Open a terminal and run nu to start the Nushell shell.
- 3List files as a table. Run ls to see the current directory as rows you can work with.
- 4Filter with where. Pipe into where, for example ls | where type == "dir", to keep only matching rows.
- 5Open a structured file. Run open Cargo.toml | get package to load a TOML file and select one part of it.
- 6Find your config. Run $nu.config-path to see where config.nu is, then customise it using the Nushell book.
Install Nushell on Linux, macOS or Windows
The quickest way to install Nu is with a package manager. The project's README gives Homebrew for Linux and macOS and winget for Windows.
Detailed installation instructions are in the installation chapter of the Nushell book at nushell.sh. The README also notes that Nu is available through many package managers, and that the team has a platform support policy you can read in its devdocs.
# Linux and macOS
brew install nushell
# Windows
winget install nushellRun your first commands and pipelines
Commands are separated by the pipe symbol (|), and data flows left to right. The README describes three kinds of pipeline commands: ones that produce a stream (such as ls), ones that filter a stream (such as where), and ones that consume the output (such as table).
Because you usually want to see the result of a pipeline, table is assumed at the end, so the two examples below show the same listing of directories.
- ls shows the contents of the current directory as a table of rows.
- where type == "dir" keeps only the rows whose type is dir.
- ps lists running processes, and ps | where cpu > 0 filters them by CPU use.
ls | where type == "dir" | table
ls | where type == "dir"
ps | where cpu > 0Open files and read them as data
Nu can load file and URL contents as raw text or as structured data, if it recognises the format. The README's example loads a .toml file and then drills into it.
You can pipe the result into get to pull out one column, and use a dotted path to go further down into the data.
open Cargo.toml
open Cargo.toml | get package
open Cargo.toml | get package.versionFind and edit your config file
Nushell ships default configuration files, which are the files you get the first time you start it. You customise these for your own needs. To see where config.nu is on your system, run the command below.
For all Nushell documentation, the README points to the Nushell book, which has a configuration chapter.
$nu.config-pathKnow the limits before you switch
The README says the project has reached a minimum-viable-product level of quality. Many people use it as a daily driver, but some commands may be unstable and the design is subject to change as it matures.
Nu is a different language from POSIX shells. Existing bash scripts will not simply run in it, so keep your current shell for scripts you depend on and try Nu alongside it.
- Good fit: terminal-heavy developers who want to query files, processes or config files as data.
- Poor fit: anyone who needs a fully stable, unchanging shell or strict POSIX scripts.
Extend Nushell with plugins
Nu supports plugins that add functionality and follow the same structured data model as built-in commands. Plugins are binaries on your path named nu_plugin_*, and they talk to Nu through a simple JSON-RPC protocol.
The README points to examples in the crates/nu_plugins_* directories.
What people use it for
- List only the directories in a folder with ls | where type == "dir".
- Find running processes using a lot of CPU with ps | where cpu > 0.
- Read a TOML file as data and pull out one value, such as the package version, with open and get.
- Keep one command set in config.nu and compose commands in new ways with pipelines.
Frequently asked questions
How do I install nushell?
On Linux or macOS, run brew install nushell with Homebrew. On Windows, run winget install nushell with winget. The README also links to the installation chapter of the Nushell book for detailed instructions.
Is nushell free and open source?
Yes. The nushell/nushell project is MIT licensed and written in Rust.
Is nushell stable enough for daily use?
The README says the project is at a minimum-viable-product level. Many people use it as a daily driver, but some commands may be unstable and the design may still change.
Can I run my bash scripts in nushell?
Not directly. Nu is a different language, and the README says existing bash scripts will not simply run in it. Keep your current shell for scripts you rely on.
Where is the nushell config file?
Run $nu.config-path inside Nushell to see where config.nu is on your system. The default configuration files are in the sample_config directory of the repository.
How does nushell compare with bash, zsh, fish or PowerShell?
Nushell passes structured data such as tables and records between commands, while bash, zsh and fish pass text. PowerShell also works with objects, but it is a different project. Choose Nushell if you want to query data in the terminal and are happy with a young project.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Nushell suits developers who spend a lot of time in the terminal and want to query files, processes and config files as structured data. It is a poor choice if you need a fully stable shell or depend on POSIX scripts, since the project describes itself as minimum-viable-product and its design may change. Try it alongside your current shell before making it your default.
Install options & downloads