Nvim Tree
A fast, Lua-powered file explorer sidebar for Neovim
Nvim Tree is a powerful file explorer designed for Neovim users who want a simple and efficient way to browse files, navigate folders, and manage project directories. With its clean interface and convenient navigation features, Nvim Tree makes working with files and code more organized directly within the Neovim editor.
- Written in Lua
- Neovim plugin
- Community maintained
- Unofficial resource
- lua
- nvim-tree.lua
- keymaps.lua
- options.lua
- init.lua
- README.md
Icons, git status and diagnostics render inline beside each entry when the matching integrations are enabled.
Git status
Modified, staged and ignored files marked inline
Diagnostics
Optional LSP severity signs beside file names
Easy to Understand
Clear guides written in plain language, with the configuration shown as small, readable pieces rather than one wall of Lua.
Feature Focused
Explore what the sidebar actually does: file operations, filters, git signs, diagnostics and the keymaps behind them.
Updated Resources
Behaviour changes between releases, so version-dependent details are pointed out instead of quietly assumed.
User Friendly
Simple guidance for a first install, plus the deeper options experienced users reach for later on.
What Is nvim tree?
nvim tree is a file explorer plugin for Neovim, distributed as nvim-tree.lua and written entirely in Lua. It renders a directory tree in a side window, keeps that window in sync with the directory you opened Neovim in, and lets you act on the files it shows. Everything happens inside the editor: the tree is an ordinary Neovim window with its own buffer and its own keymaps, so it behaves the way the rest of your editor behaves.
The reason people reach for it is simple. Neovim ships with netrw, a built-in file browser, but netrw was designed for a different era of Vim and its interface shows it. nvimtree replaces that experience with a persistent sidebar, optional file-type icons, folder expansion you can drive from the keyboard, and file operations that read like the ones in a graphical editor – add, rename, copy, cut, paste, delete – without leaving the terminal.
Configuration is a single Lua call. You require the module and call setup(), optionally passing a table of options that control the view width, the renderer, filters, git integration, diagnostics and the actions the plugin performs when you open a file. Calling setup once is important: the plugin expects to be initialised a single time, and most confusing behaviour reported by new users comes from calling it twice or from configuring options before it runs.
It is worth being precise about what nvimtree is not. It is not a file manager for your operating system, it is not a fuzzy finder, and it does not replace a project-wide search tool. It is a tree view of a directory with editing actions attached. Many people pair it with a fuzzy finder for jumping to known files and keep nvimtree for the moments when they want to see structure – a new codebase, a nested folder they half remember, or a set of files they are about to move.
At a glance
- Type — Neovim plugin
- Language — Lua
- Interface — side window tree
- Setup — single setup() call
- Icons — optional, via devicons
- Git signs — optional integration
- Licence & source — upstream repo
nvimtree.com is an independent informational site. It is not officially owned, operated, endorsed or approved by the nvim-tree project, its maintainers or the Neovim project. Always confirm details against the plugin’s own documentation.
A window, not an app
The tree lives in a normal Neovim window, so splits, tabs and window commands all work the way you already expect them to.
Keyboard first
Every action has a default mapping, and the in-tree help list shows the current bindings for the version you actually have installed.
Configured in one place
Options are passed as a Lua table to setup(), which keeps the whole explorer configuration in a single readable block of your config.
nvim tree Features
Six things the sidebar does that account for most of why people install it.
Project tree sidebar
A persistent side window shows the directory you opened Neovim in. Folders expand and collapse from the keyboard, the tree scrolls independently of your code, and the window can be toggled away when you want the full width back for editing.
File operations in place
Create, rename, copy, cut, paste and remove entries directly from the tree. The default mappings follow a short, memorable set of single keys, and destructive actions ask for confirmation before anything is written to disk.
Git status integration
When git integration is enabled, the tree marks files and folders according to their status in the repository - modified, staged, untracked or ignored - so you can see the shape of your working tree without running a separate command.
Diagnostics signs
The renderer can display diagnostic severity next to file names, sourced from Neovim's diagnostics. Errors surface at the file level and can propagate up to parent folders, which makes a broken file easy to find in a large project.
Filters and live search
Hide dotfiles, hide git-ignored paths, or apply your own custom filter list to keep build output and vendor folders out of the way. A live filter narrows the visible tree as you type and clears again when you are done.
Icons and highlight control
File-type icons come from the optional devicons plugin and a Nerd Font, while the renderer exposes highlight groups for folders, files, git states and indent markers - so the tree can be styled to match your colourscheme rather than fighting it.
How nvim tree Works
From an empty config to a working sidebar, in the order the pieces actually run.
The plugin is installed
Your plugin manager clones the repository into Neovim’s runtime path so the Lua modules can be loaded.
setup() runs once
A single call initialises the explorer, merges your options over the defaults and registers the plugin’s user commands.
The tree opens in a window
A command such as toggle creates a side window, reads the current directory and renders it as an indented, navigable buffer.
Keys act on the entry
Mappings inside that buffer open files, expand folders or run file actions against whatever line the cursor is on.
Why People Search for nvim tree
Search traffic around this keyword is remarkably consistent, and it is almost never someone looking to buy something. It is someone in the middle of setting up an editor, with a config file open in one window and a half-working sidebar in another. The questions cluster into a handful of shapes, and knowing those shapes is the fastest way to find the right part of the documentation.
The other recurring theme is drift. Neovim moves quickly, and so does the plugin. A guide written two years ago can be accurate in spirit and wrong in detail – option names get renamed, keymap configuration moves into a different function, minimum versions rise. When something in a tutorial does not work, the version gap is the first thing worth checking, not the last.
- Updates and release notes
- Uninstalling cleanly
- Alternatives and comparisons
Understanding what it is
Many searches start after seeing the sidebar in someone else's screenshot or dotfiles, with no idea which plugin produced it.
Installation and configuration
Plugin managers differ, and people want a config snippet that matches the manager they already use rather than a generic one.
Compatibility questions
Which Neovim version is required, whether a Nerd Font is needed, and whether it works on Windows or inside WSL.
Something is broken
Empty icons, a tree that will not open, keymaps that behave differently to the tutorial being followed.
nvim tree Compatibility
What has to be true on your machine before the sidebar behaves the way the screenshots suggest.
Neovim version
The plugin targets recent Neovim releases and its minimum supported version has risen over time. The release you install decides the requirement, so check the documentation for the tag or branch your plugin manager pinned.
Operating systems
It runs wherever Neovim runs - Linux, macOS, BSD, Windows and WSL. Path handling and external tools such as git or a trash command behave differently per platform, which is where most platform-specific reports come from.
Terminal and fonts
Icons are optional. If you want them, you need a patched Nerd Font selected in your terminal or GUI client plus the devicons plugin. Without a patched font the tree still works, it simply shows placeholder glyphs.
Companion plugins
Devicons for icons, an LSP setup for diagnostic signs, and git available on your PATH for status marks. None of these are required to open the tree; each one only enables the feature it belongs to.
Version-dependent details
Requirements, default keymaps and option names have all changed across releases of this plugin. Nothing on this page should be treated as a fixed guarantee for every version - where behaviour varies, confirm it against the documentation shipped with the copy you installed, or with :help nvim-tree inside Neovim.
How to Use nvim tree
The handful of actions that cover almost everything you will do in the sidebar.
Open and close the tree
Run the toggle command, or map it to a key you can reach quickly. Most people bind it to a leader mapping so the sidebar becomes a single keystroke away.
Move around the tree
Navigation uses ordinary Neovim motions, because the tree is an ordinary buffer. Enter opens the entry under the cursor; on a folder it expands or collapses it.
Create and rename files
The add action prompts for a path relative to the selected node, and ending that path with a separator creates a directory instead of a file. Rename works the same way.
Move, copy and delete
Cut, copy and paste operate through a small internal clipboard, so you mark a node first and paste it into the destination folder afterwards.
Reveal the file you are editing
The find-file command jumps the tree to the buffer you currently have open, which is the fastest way to orient yourself in an unfamiliar repository.
Read the built-in help
Inside the tree, the help mapping lists every binding that is active for your version. It is the only keymap reference guaranteed to match the copy you have installed.
How to Install nvim tree
A six-part sequence that works regardless of which plugin manager you prefer.
Requirements
You need a supported Neovim version, a plugin manager, and – only if you want icons – a patched Nerd Font plus the devicons plugin. Check what you have with nvim --version before anything else, because a version mismatch explains a large share of failed installs.
Prepare your config
Disable the built-in netrw explorer before the plugin loads, and turn on true colour. These two lines belong near the top of your configuration, above the plugin manager bootstrap.
— disable netrw at the very start of init.lua
vim.g.loaded_netrw = 1
vim.g.loaded_netrwPlugin = 1
— enable 24-bit colour so highlights render correctly
vim.opt.termguicolors = true
Install with a plugin manager
Add the plugin to whichever manager you already use – lazy.nvim, packer, vim-plug or another – listing the devicons plugin as a dependency if you want file icons. Use the repository path given in the project’s current documentation; the plugin moved to an organisation namespace some time ago, so older guides may reference the previous path.
Configure
Call setup() exactly once, after the plugin is available. An empty table gives you the defaults; a populated one overrides only the keys you name. Start small and add options as you find the need for them.
require(“nvim-tree”).setup({
view = { width = 32 },
renderer = { group_empty = true },
filters = { dotfiles = false },
})
Verify
Restart Neovim and run the toggle command. If the window opens with your project in it, the install worked. If anything looks wrong, run :checkhealth nvim-tree – it reports missing dependencies and common configuration mistakes in a readable form.
Update later
Updates go through the same plugin manager that installed it. Read the release notes before syncing a major jump: option names and default mappings have changed between versions, and a five-minute read is cheaper than an afternoon of debugging.
Install from a source you trust
This page does not host or link to plugin downloads. Install through your plugin manager from the project's own repository, and treat copies redistributed elsewhere with caution - especially anything asking you to run an installer script.
One sidebar, one context
The strongest argument for the sidebar is not any single feature – it is that the whole loop stays inside the editor. You see the structure of a project, move to the file you want, act on it, and go straight back to editing without a context switch to a terminal or a second application.
That matters most in unfamiliar code. A fuzzy finder is faster when you already know the file name; a tree is faster when you do not. Having both open and switching between them by intent is the pattern most long-term users settle into, and it is why the plugin tends to stay in configurations for years.
- See the shape of an unfamiliar repository
- Act on files without a shell round trip
- Keep windows, splits and tabs behaving normally
Loads only when you ask
Most plugin managers can defer the plugin until the toggle command or a key is used, so an unused sidebar costs nothing at startup.
Fits your colourscheme
Highlight groups are exposed for folders, files, git states, diagnostics and indent markers, so the tree can be themed rather than tolerated.
Mouse optional, not required
Everything is reachable from the keyboard, and the tree still responds to a mouse if your terminal passes those events through.
nvim tree Comparison
The honest comparison is with the explorer Neovim already gives you, not with a graphical IDE. netrw is capable and costs nothing to keep; nvim tree trades a dependency for a persistent tree and a richer set of file actions. Neither choice is wrong, and plenty of people use both.
| Area | nvim tree | netrw (built in) | Notes |
|---|---|---|---|
| Availability | Installed as a plugin | Ships with Neovim | netrw needs nothing; nvim tree needs a plugin manager. |
| Presentation | Persistent side window tree | Directory listing buffer | Both are ordinary buffers in ordinary windows. |
| File actions | Add, rename, copy, cut, paste, remove | Create, rename, delete | Default keys differ; check each tool’s own help. |
| Icons | Optional, via devicons and a Nerd Font | Plain text | Icons are cosmetic and can be left off entirely. |
| Git status | Optional integration | Not provided | Requires git available to Neovim. |
| Configuration | Lua table passed to setup() | Vim global variables | One style is not better; they are simply different. |
| Maintenance | Community project, updated independently | Maintained with the editor | Plugin updates can introduce breaking changes. |
Highlights and Trade-offs
Worth reading before you add anything to a configuration you rely on.
nvim tree Highlights
- Structure is visible at a glance, which helps most in new codebases
- File operations happen where you are already working
- Configuration is a single, readable Lua table
- Written in Lua and can be deferred until first use
- Optional git and diagnostic signs add context without extra commands
- Highlight groups make it themeable rather than fixed
Things to Consider
- It is a dependency, and dependencies change under you
- Default keymaps and option names have shifted between versions
- Icons need a patched font, which some terminals make awkward
- A tree is slower than a fuzzy finder when you know the file name
- Very large directories can feel heavy without filters configured
- Older tutorials frequently describe an interface that no longer matches
Common nvim tree Problems & Solutions
Six failures that account for most first-week frustration, with the reason behind each one.
The tree will not open
Symptom. The command is unknown, or nothing happens when you run it.
Likely reason. The plugin has not loaded, or setup() was never called. Lazy-loading rules that never trigger are a common cause.
Try this. Confirm the plugin manager actually installed it, then make sure setup runs at startup. :checkhealth nvim-tree will usually name the problem directly.
Icons show as boxes or blanks
Symptom. File names appear with placeholder glyphs instead of icons.
Likely reason. The terminal or GUI is not using a patched Nerd Font, or the devicons plugin is not installed.
Try this. Select a patched font in your terminal profile and install devicons. If you would rather not use a font at all, disable icons in the renderer options instead.
netrw still opens for directories
Symptom. Opening a folder path gives you the old built-in explorer.
Likely reason. netrw was not disabled, or it was disabled after the plugin loaded.
Try this. Set both netrw globals near the very top of your config, before the plugin manager runs, then restart Neovim rather than sourcing the file again.
Git status marks are missing
Symptom. Modified and untracked files look identical in the tree.
Likely reason. Git integration is disabled, git is not on the PATH Neovim sees, or the directory is not a repository.
Try this. Check that git integration is enabled in your options and that :!git status works from inside Neovim. Health checks report a missing git binary.
Keymaps do not match the guide
Symptom. Keys from a tutorial do nothing, or do something else entirely.
Likely reason. Keymap configuration has changed across releases, and older articles describe the previous approach.
Try this. Open the tree and use the built-in help mapping to list the bindings that are actually active. Configure custom maps the way your installed version documents.
Colours look wrong or washed out
Symptom. Highlights are dim, inverted, or barely visible against the background.
Likely reason. True colour is off, or your colourscheme does not define the plugin’s highlight groups.
Try this. Enable termguicolors and confirm your terminal supports it, then override the specific highlight groups you dislike in your colourscheme setup.
nvim tree Tips & Best Practices
Small decisions that make the difference between a config you maintain and one you fight.
Start with an empty options table
Run setup with no options first and use the plugin as shipped for a few days. You will have a far better idea of what you actually want to change.
Pin versions in your lockfile
Commit your plugin manager's lockfile alongside your config. When an update breaks something, you can reproduce the working state immediately.
Filter noisy directories early
Add build output, dependency folders and caches to your filter list. A tree that hides the irrelevant is much faster to read than a complete one.
Keep one leader mapping for toggle
A single, memorable binding beats several partially remembered ones. Reveal-current-file is the only other mapping most people use daily.
Run the health check after every change
It takes a second and catches missing dependencies, stale options and version mismatches before they turn into a debugging session.
Trust :help over any article
Including this one. The help files ship with the version you installed, which makes them the only reference guaranteed to describe your copy.
Complete nvim tree Guide
Everything above in one continuous read, for people who would rather not jump between sections.
Where nvim tree fits in a Neovim setup
A Neovim configuration is a stack of small decisions, and file navigation is one of them. Some people never install an explorer at all, relying on a fuzzy finder and buffer list. Others want to see a project laid out. nvim tree serves the second group without taking anything away from the first: it is one window, opened on demand, and the rest of your editor is untouched while it is closed.
Because it is written in Lua and configured through a single function call, it reads like the rest of a modern configuration rather than like a bolted-on legacy plugin. That consistency is a real part of its appeal – the same table-of-options pattern you use for your LSP client, your completion engine and your statusline works here too.
Who it is for
It suits anyone who regularly opens repositories they did not write. It suits people moving from a graphical editor who miss having a project pane. It suits anyone who restructures directories often, because moving files from the tree is quicker than typing paths. It is less compelling if you work in a handful of files you already know by name, where a fuzzy finder will always be faster.
What it needs from you
Three things: a supported Neovim version, one call to setup, and netrw disabled so the two explorers do not compete. Everything beyond that is optional. Icons need a patched font and the devicons plugin. Git marks need git. Diagnostic signs need a working LSP or diagnostic source. Skip all three and you still have a functioning tree.
Living with version changes
This is the part guides usually omit. The plugin is actively developed, and across its history it has renamed options, restructured how keymaps are declared, and raised its minimum Neovim version more than once. None of that is unusual for a community plugin, but it does mean an article’s age matters as much as its accuracy.
The practical response is to treat the shipped documentation as the source of truth. Read the release notes before a major update, keep your lockfile in version control, and when something stops working, check whether it changed before assuming you broke it.
Getting more out of it
Once the basics are in place, the options worth exploring are the renderer, the filters and the view. The renderer controls what each line shows – icons, git marks, indent guides, whether empty nested folders are grouped onto one line. Filters decide what is hidden. The view controls width, side and whether the tree can open as a floating window.
Beyond that, the actions table changes what happens when you open a file: whether the tree closes behind you, whether files open in a split, how the window is resized. These are small ergonomic choices, but they are the ones that make a tool feel like it belongs to you rather than to whoever wrote the tutorial you copied.
When to look elsewhere
If you want a two-pane commander, a netrw-style buffer you edit like text, or a floating fuzzy browser, other plugins target those shapes directly and will fit better. There is no prize for using the most popular option, and Neovim’s plugin ecosystem is unusually rich in this particular category. Try one for a week before deciding.
Read this first if you are new
Install, disable netrw, call setup with an empty table, bind one toggle key. Stop there for a week. Every other option makes more sense once you have used the defaults.
Read this first if something broke
Run the health check, then compare your config against the documentation for your installed version rather than against a tutorial. Version drift explains most reports.
nvim tree Download & Resources
Links below are editable placeholders. Replace each button URL in Elementor with the destination you have verified – no download source is asserted here.
Before you install anything: use reputable sources, prefer your plugin manager over manual copies, and check the version requirements against the Neovim build you are running. Redistributed archives and installer scripts from unfamiliar sites are worth avoiding entirely.
nvim tree Frequently Asked Questions
Twenty answers covering installation, compatibility, updates, failures and the things people wish they had been told first.
What is nvim tree?
nvimtree is the common name for nvim-tree.lua, a file explorer plugin for Neovim written in Lua. It renders the directory you are working in as a tree inside a side window and lets you open, create, rename, move and delete files from that window. It is a community project installed through a plugin manager, not part of Neovim itself.
How does nvim tree work?
Your plugin manager places the Lua modules on Neovim’s runtime path. Calling setup initialises the plugin and registers its user commands. When you run one of those commands, it opens a window, reads the directory, and renders it as an indented buffer. Keymaps active in that buffer act on whichever entry the cursor is sitting on.
What are the main nvim tree features?
A persistent project tree, file operations from inside the tree, optional file-type icons, optional git status marks, optional diagnostic signs, filters for hiding dotfiles and ignored paths, a live filter for narrowing the view, and highlight groups that let the tree match your colourscheme.
Is nvim tree easy to use?
The basics are, yes. Toggle the tree, move with normal motions, press Enter to open. The file operations take a little longer to internalise because they use single-key mappings, but the in-tree help list shows every active binding for your version, which shortens the learning curve considerably.
What devices and systems support nvim tree?
Anywhere Neovim runs: Linux, macOS, BSD, Windows and WSL. It is a terminal-oriented plugin, so it works in a terminal emulator or a GUI client. Platform differences show up mainly around path handling and external tools such as git or a system trash command.
How do I install nvim tree?
Add the plugin to your plugin manager, optionally with the devicons plugin as a dependency, then call setup once in your configuration. Disable netrw before the plugin loads and enable termguicolors. Use the repository path from the project’s current documentation, since it moved namespaces some time ago.
How do I update nvim tree?
Through the same plugin manager that installed it – a sync or update command depending on which one you use. Read the release notes first when the jump is a large one, because option names and default mappings have changed between versions, and update your lockfile afterwards so the state is reproducible.
Why is nvim tree not working?
The usual causes are: setup was never called, the plugin was lazy-loaded on a trigger that never fires, your Neovim version is below the minimum for the release installed, or there is an error earlier in your config that stops later lines from running. Running the health check normally identifies which one applies.
What should I check before installation?
Your Neovim version, that a plugin manager is set up and working, and whether you want icons – because icons mean installing devicons and selecting a patched Nerd Font in your terminal. It is also worth backing up your configuration or committing it first, so you can undo cleanly.
Does compatibility vary by version?
Yes, meaningfully. The minimum supported Neovim version has increased across releases, option names have been renamed, and the way custom keymaps are declared has been restructured. Always read the documentation that matches the tag or branch your plugin manager installed rather than the newest article you find.
Where can I find nvim tree resources?
The most reliable references are the help files shipped with the plugin, reachable through Neovim’s help system, and the project’s own repository documentation. Community discussions and dotfile repositories are useful for examples, but treat them as starting points rather than as specifications.
How do I troubleshoot nvim tree?
Start with the plugin’s health check, which reports missing dependencies and common misconfigurations. If that is clean, test with a minimal configuration containing only this plugin – if the problem disappears, something else in your config is interfering, and you can bisect from there.
Can I uninstall nvim tree?
Yes. Remove its entry from your plugin manager, run whatever clean or sync command that manager provides, and delete the setup call and any related keymaps from your configuration. If you want the built-in explorer back, remove the two lines that disabled netrw as well.
What should I do before updating?
Commit your configuration and lockfile so you can roll back, skim the release notes for breaking changes, and make a note of any option names or custom mappings you rely on. Updating in the middle of urgent work is the one habit most likely to cost you an afternoon.
Does nvim tree require additional software?
Only Neovim itself. Icons require the devicons plugin plus a patched Nerd Font, git status marks require git to be reachable from Neovim, and diagnostic signs require a diagnostic source such as a configured language server. Every one of those is optional and can be left out.
How can I check my current version?
Your plugin manager is the quickest answer – most show the installed commit or tag in their status interface, and lockfiles record it explicitly. Failing that, the plugin is a git clone inside Neovim’s data directory, so the repository log there tells you exactly what you have.
What are common nvim tree problems?
Missing or broken icons from an unpatched font, netrw opening instead of the tree, keymaps that differ from an older tutorial, absent git marks when git integration is off, and dim colours when true colour is not enabled. Almost all of them are configuration or environment issues rather than plugin bugs.
Where can I learn more about nvim tree?
Neovim’s built-in help for the plugin is the most detailed and most current reference, since it ships with the copy you installed. The repository documentation covers the same ground, and reading other people’s published configurations is a good way to see how the options combine in practice.
Is nvimtree.com an official website?
No. This is an independent informational resource. It is not owned, operated, endorsed or approved by the nvim-tree project, its maintainers, or the Neovim project, and it hosts no downloads. Anything here that conflicts with the official documentation should be resolved in favour of the official documentation.
What should new nvim tree users know?
Three things. Call setup exactly once. Disable netrw before the plugin loads. Use the in-tree help list instead of memorising keys from an article, because it always matches your installed version. Get those right and most of the problems people write about never appear.