Aliases in Nushell offer a way of doing a simple replacement of command calls (both external and internal commands). This allows you to create a shorthand name for a longer command, including its default arguments.

For example, let's create an alias called ll which will expand to ls -l.

> alias ll = ls -l

We can now call this alias:

> ll

Once we do, it's as if we typed ls -l. This also allows us to pass in flags or positional parameters. For example, we can now also write:

> ll -a

And get the equivalent to having typed ls -l -a.

List all loaded aliases

Your useable aliases can be seen in scope aliases and help aliases.


To make your aliases persistent they must be added to your file by running config nu to open an editor and inserting them, and then restarting nushell. e.g. with the above ll alias, you can add alias ll = ls -l anywhere in

$env.config = {
    # main configuration

alias ll = ls -l

# some other config and script loading

Piping in aliases

Note that alias uuidgen = uuidgen | tr A-F a-f (to make uuidgen on mac behave like linux) won't work. The solution is to define a command without parameters that calls the system program uuidgen via ^.

def uuidgen [] { ^uuidgen | tr A-F a-f }

See more in the custom commands section of this book.

Or a more idiomatic example with nushell internal commands

def lsg [] { ls | sort-by type name -i | grid -c | str trim }

displaying all listed files and folders in a grid.

Replacing existing commands using aliases

Caution! When replacing commands it is best to "back up" the command first and avoid recursion error.

How to back up a command like ls:

alias core-ls = ls    # This will create a new alias core-ls for ls

Now you can use core-ls as ls in your nu-programming. You will see further down how to use core-ls.

The reason you need to use alias is because, unlike def, aliases are position-dependent. So, you need to "back up" the old command first with an alias, before re-defining it. If you do not backup the command and you replace the command using def you get a recursion error.

def ls [] { ls }; ls    # Do *NOT* do this! This will throw a recursion error

#Error: nu::shell::recursion_limit_reached
#  × Recursion limit (50) reached
#     ╭─[C:\Users\zolodev\AppData\Roaming\nushell\]
# 807 │
# 808 │ def ls [] { ls }; ls
#     ·           ───┬──
#     ·              ╰── This called itself too many times
#     ╰────

The recommended way to replace an existing command is to shadow the command. Here is an example shadowing the ls command.

# An escape hatch to have access to the original ls command
alias core-ls = ls

# Call the built-in ls command with a path parameter
def old-ls [path] {
  core-ls $path | sort-by type name -i

# Shadow the ls command so that you always have the sort type you want
def ls [path?] {
  if $path == null {
    old-ls .
  } else {
    old-ls $path
Contributors: Justin Ma, Antoine Stevan, Charles Stieffenhofer, Ibraheem Ahmed, JT, Jakub Žádník, Jonathan Turner, Michael Angerman, Richard Neumann, TornaxO7, Zhora Trush, Zolo, mh-trimble