# Overlays

Overlays act as "layers" of definitions (custom commands, aliases, environment variables) that can be activated and deactivated on demand.
They resemble virtual environments found in some languages, such as Python.

_Note: To understand overlays, make sure to check [Modules](modules.md) first as overlays build on top of modules._

## Basics

First, Nushell comes with one default overlay called `zero`.
You can inspect which overlays are active with the [`overlay list`](/commands/docs/overlay_list.md) command.
You should see the default overlay listed there.

To create a new overlay, you first need a module:

```nu
module spam {
    export def foo [] {
        "foo"
    }

    export alias bar = echo "bar"

    export-env {
        load-env { BAZ: "baz" }
    }
}
```

We'll use this module throughout the chapter, so whenever you see `overlay use spam`, assume `spam` is referring to this module.

::: tip
The module can be created by any of the three methods described in [Modules](modules.md):

- "inline" modules (used in this example)
- file
- directory
:::

To create the overlay, call [`overlay use`](/commands/docs/overlay_use.md):

```nu
overlay use spam

foo
# => foo

bar
# => bar

$env.BAZ
# => baz

overlay list
# => ───┬──────
# =>  0 │ zero
# =>  1 │ spam
# => ───┴──────
```

It brought the module's definitions into the current scope and evaluated the [`export-env`](/commands/docs/export-env.md) block the same way as [`use`](/commands/docs/use.md) command would (see [Modules](modules.md#environment-variables) chapter).

::: tip
In the following sections, the `>` prompt will be preceded by the name of the last active overlay.
`(spam)> some-command` means the `spam` overlay is the last active overlay when the command was typed.
:::

## Removing an Overlay

If you don't need the overlay definitions anymore, call [`overlay hide`](/commands/docs/overlay_hide.md):

```nu
(spam)> overlay hide spam

(zero)> foo
Error: Can't run executable...

(zero)> overlay list
───┬──────
 0 │ zero
───┴──────
```

The overlays are also scoped.
Any added overlays are removed at the end of the scope:

```nu
(zero)> do { overlay use spam; foo }  # overlay is active only inside the block
foo

(zero)> overlay list
───┬──────
 0 │ zero
───┴──────
```

The last way to remove an overlay is to call [`overlay hide`](/commands/docs/overlay_hide.md) without an argument which will remove the last active overlay.

## Overlays Are Recordable

Any new definition (command, alias, environment variable) is recorded into the last active overlay:

```nu
(zero)> overlay use spam

(spam)> def eggs [] { "eggs" }
```

Now, the `eggs` command belongs to the `spam` overlay.
If we remove the overlay, we can't call it anymore:

```nu
(spam)> overlay hide spam

(zero)> eggs
Error: Can't run executable...
```

But we can bring it back!

```nu
(zero)> overlay use spam

(spam)> eggs
eggs
```

Overlays remember what you add to them and store that information even if you remove them.