Setup nnn Terminal File Manager on MacOS

nnn (n³) is a text-based file manager for the terminal. It is a significant improvement over ls and cd for moving around the file system.

Execute the following command to install nnn.

brew install nnn

If you don’t have brew, install it first. It is highly recommended for Package Management on MacOS. For other ways of installing nnn, see the installation guide here.

After installation, run nnn to launch it in the terminal.

nnn makes it pretty easy to navigate by using the arrow keys. You can also use Vim key bindings if that’s your thing.

It is so convenient to use Left key for moving up a directory, Right key for opening a directory or a file and Up/Down keys to move around within a directory.

Some of the other useful shortcuts are:

.	toggle hidden files
d	toggle detail mode (show size, permissions and timestamps)
q	quit
/	filter (press / and start typing to filter the contents of the current directory. It is very useful and quick. Press / twice, it changes to \ and type a regular expression for filtering)
‘	first file match (press ' and then a character to go to the first file/diectory starting with that character)
^n	toggle type-to-navigate (type to filter and navigate, rather than commands)
B	bookmark the current directory (b to list all bookmarked directories)
~	takes you home (pressing ~ again takes you back). ` takes you to root, - back and @ start.
^T	toggle sort order (d enables the du (disk usage) mode where you can see the size of directories)
]	command prompt (^] for shell)
?	get help on all the keyboard shortcuts and configuration

I have pointed out the some of the interesting ones. Obviously, there are also commands for copy, move, selection, bulk rename, delete, archive etc.

There is also support for mouse for certain operations.

CD on Quit

To make nnn a replacement of CD, we need nnn to change directory on quit. To set this up, place the following code in ~/.zshrc file.

This creates a new alias n for launching nnn. When launched with the new alias n, your terminal directory will be changed on quitting nnn.

You can find more details on this here.

n ()
{
    # Block nesting of nnn in subshells
    [ "${NNNLVL:-0}" -eq 0 ] || {
        echo "nnn is already running"
        return
    }

    # The behaviour is set to cd on quit (nnn checks if NNN_TMPFILE is set)
    # If NNN_TMPFILE is set to a custom path, it must be exported for nnn to
    # see. To cd on quit only on ^G, remove the "export" and make sure not to
    # use a custom path, i.e. set NNN_TMPFILE *exactly* as follows:
    #      NNN_TMPFILE="${XDG_CONFIG_HOME:-$HOME/.config}/nnn/.lastd"
    export NNN_TMPFILE="${XDG_CONFIG_HOME:-$HOME/.config}/nnn/.lastd"

    # Unmask ^Q (, ^V etc.) (if required, see `stty -a`) to Quit nnn
    # stty start undef
    # stty stop undef
    # stty lwrap undef
    # stty lnext undef

    # The command builtin allows one to alias nnn to n, if desired, without
    # making an infinitely recursive alias
    command nnn "$@"

    [ ! -f "$NNN_TMPFILE" ] || {
        . "$NNN_TMPFILE"
        rm -f "$NNN_TMPFILE" > /dev/null
    }
}

Stop Rollover

As we move to the bottom of the directory, it rolls over to the top by default. I don’t like rollover. To turn it off, we can launch nnn with -R parameter.

nnn -R

To avoid typing this every time, I include it to the n() function added to ~/.zshrc file. Modify the following line of the function as follows:

command nnn -R "$@"

Sync selection with clipboard

Following syncs the selected file paths with the clipboard.

nnn -x

I also include it in my n() function in ~/.zshrc file.

command nnn -xR "$@"

Plugins

This is all very good but plugins make it so much better. It is easy to write a plugin yourself.

nnn comes with a lot of plugins but they are not installed by default. To get started with plugins, run the following command.

sh -c "$(curl -Ls https://raw.githubusercontent.com/jarun/nnn/master/plugins/getplugs)"

Now, we have got all the plugins loaded into ${XDG_CONFIG_HOME:-$HOME/.config}/nnn/plugins directory.

Plugins can be assigned a shortcut key. To invoke the plugin, we have to press ;and then the plugin shortcut key.

As we have not assigned any plugin shortcuts yet, press ;and then enter key, to launch the full list of plugins. At this moment, we can use the plugins which have no dependencies. Most plugins have dependences and we need to refer to the plugin documentation to install them. You can find the list of plugins and read more about each here.

I am going to set up a few plugins which I think are essential.

Preview

preview-tui is a plugin for file preview. I tried setting it up on MacOS builtin terminal app, Warp, iTerm2 and WezTerm. It is not supported on Warp and doesn’t work in the built-in terminal app in my setup at least. It works in iTerm2 but the previews are slow. It works like a charm in WezTerm, so that’s what I recommend if you want to use previews frequently.

We need to add the following line in ~/zshrc for previews to work.

export NNN_FIFO=/tmp/nnn.fifo

Let’s set a shortcut for the preview plugin by adding the following to ~/zshrc. This sets p as the shortcut key for preview plugin.

export NNN_PLUG='p:preview-tui;'

To close the preview, run the plugin again or press ^C on the preview window.

We need to install more dependencies for previews to work for different file types but images and text files should start working at this point.

Let’s install tree to see the preview of directories:

brew install tree

I would recommend installing the following:

tree	preview directory tree structure
poppler	preview pdf
bat	syntax highlighting for code files
glow	preview markdown files

All of the above can be installed using brew.

Look at the plugin documentation for dependencies for other file types.

Finder

The finder plugin integrates the find command with nnn.

Let’s add a shortcut to make it easier to launch. Change the NNN_PLUG variable in ~/.zshrc as follows:

export NNN_PLUG='p:preview-tui;f:finder;'

You may need to update the bash to latest version.

Fuzzy find (fzcd)

This command let you fuzzy find a file or directory in the current tree (recursively). It uses fzf which is amazing tool.

Install fzf

brew install fzf

Add a shortcut for it in ~/.zshrc file

export NNN_PLUG='p:preview-tui;f:finder;d:fzcd;'