How do I install Nvim Tree with packer.nvim?

With packer.nvim, use the use function with 'nvim-tree/nvim-tree.lua', set requires to include 'nvim-tree/nvim-web-devicons' for file icons, add a config function that calls require('nvim-tree').setup{}, and optionally set run = ':TSUpdate' if you use treesitter parsers. Note that packer.nvim is now in maintenance mode and lazy.nvim is the recommended plugin manager for new configurations.

How do I perform a manual installation of Nvim Tree?

For manual installation, clone or download the repository into your Neovim packages directory. The standard path is ~/.local/share/nvim/site/pack/nvim-tree/start/nvim-tree.lua on Linux and macOS, or ~/AppData/Local/nvim-data/site/pack/nvim-tree/start/nvim-tree.lua on Windows. Neovim will automatically load plugins from the start/ directory on launch. You still need to call the setup function in your init.lua.

What should I do immediately after installing Nvim Tree?

After installation, add the require('nvim-tree').setup{} call to your init.lua with your preferred configuration options. Restart Neovim or source your configuration. Then open Nvim Tree with the default toggle keybinding or the :NvimTreeToggle command. Verify that the file tree renders correctly, icons display if nvim-web-devicons is installed, and basic navigation works before adding further customization.

What file operations does Nvim Tree support?

Nvim Tree supports creating new files and directories, renaming files and folders, deleting files and folders with optional confirmation, cutting and pasting files to move them, copying files, and trashing files if a trash utility is available. All operations are performed through keybindings and update the tree view in real time without needing a manual refresh.

How does git integration work in Nvim Tree?

Nvim Tree automatically detects git status for files and directories in your project. It shows colored indicators next to files: typically green for staged changes, red for unstaged modifications, yellow for merge conflicts, and grey for untracked files. Directories display the highest-priority status of their contained files. This works without any additional git plugin and runs git commands internally to determine file status.

Can I filter files and directories in the tree?

Yes, Nvim Tree provides multiple filtering options. You can use live filtering with a search pattern that updates as you type, configure a list of dotfiles or patterns to always hide, use custom Lua functions for advanced filtering logic, and toggle visibility of hidden files, git-ignored files, and dotfiles on the fly. Filters can be combined and configured globally in your setup or toggled interactively.

How do I customize keybindings in Nvim Tree?

Keybindings are customized through the view.mappings.list option in the setup function. Each mapping entry specifies a key, an action (either a built-in string action like 'toggle_node' or a callback function), and optional modifiers. You can override default keybindings, add new ones, and remove bindings you don't need. The mapping system supports both single-key and multi-key combinations.

Does Nvim Tree handle buffers when opening files?

Yes, Nvim Tree has intelligent buffer handling. When you open a file from the tree, it can either replace the current buffer in the window next to the tree or open in a new tab depending on your configuration. The 'actions.open_file' settings control whether the tree auto-closes, focuses the new file, or resizes the window. Buffer management integrates with Neovim's native buffer system for seamless switching.

Nvim Tree is not showing up after installation. What should I check?

First, verify the plugin is in the correct directory under your Neovim runtimepath by running :lua print(vim.inspect(vim.api.nvim_list_runtime_paths())). Check that your setup call is correct and not wrapped in a conditional that prevents execution. Ensure you have sourced your config or restarted Neovim. Run :checkhealth nvim-tree to see diagnostic information. If using a plugin manager, confirm the plugin is loaded with :Lazy or :PackerStatus.

File icons are not displaying in Nvim Tree. How do I fix this?

Missing icons almost always mean nvim-web-devicons is not installed or not loaded before Nvim Tree. Install nvim-web-devicons and ensure it is listed as a dependency or loaded before nvim-tree in your plugin manager configuration. Also verify that a Nerd Font is installed and configured in your terminal emulator, as the icons rely on Nerd Font glyph support. Run :checkhealth nvim-web-devicons for additional diagnostics.

Nvim Tree feels slow on large repositories. What can I do?

For large repositories, enable the filesystem watchers with filesystem_watchers.enable = true for faster updates. Configure filters to exclude node_modules, .git, build directories, and other large folders using the filters.exclude or filters.custom function. Reduce the number of git status checks by setting git.enable = false for non-git directories or using git.ignore = true. Disable live filtering if not needed and consider using renderer.group_empty to collapse single-child directories.

My keybindings conflict with other plugins. How do I resolve this?

Nvim Tree keybindings only apply when the tree buffer is focused, so conflicts with other plugins are rare. If conflicts occur, remap the conflicting keys in the view.mappings.list configuration. You can disable default mappings entirely with view.mappings.list = {} and define only the bindings you need. For conflicts with global Neovim keybindings, use the on_attach callback to set buffer-local keymaps that take precedence.

I see error messages when opening Nvim Tree. How do I debug this?

Start by running :checkhealth nvim-tree to identify common issues. Enable notification logging by checking the notifications setting in your config. Look at the full error with :messages. Ensure your Neovim version meets the minimum requirement. Check that all optional dependencies are correctly installed if you reference them in your config. If the error mentions a specific Lua module, verify the plugin files are intact and not corrupted.

Can I create custom actions in Nvim Tree?

Yes, Nvim Tree supports custom actions through the mapping system. In your keybinding configuration, instead of specifying a built-in action string, provide a callback function that receives a node object containing the file path, type, and other metadata. This allows you to run any Vim command or Lua function when a key is pressed on a file or directory node. Custom actions can open files in specific ways, run external commands, or integrate with other plugins.

How do I use the Nvim Tree Lua API programmatically?

The Lua API is accessed through require('nvim-tree.api'). It provides functions for common operations like api.tree.open(), api.tree.close(), api.tree.toggle(), api.tree.find_file(), api.tree.reload(), api.fs.create(), api.fs.remove(), api.fs.rename(), and api.git.reload(). These functions can be called from any Neovim Lua context, including custom keybindings, autocommands, or other plugin configurations.

How do I write a custom filter function for Nvim Tree?

Set filters.custom to a Lua function that receives the absolute file path and returns true to hide the file or false to show it. For example, to hide files larger than a certain size, you would use luv to stat the file and compare its size. To hide files matching complex patterns, use Lua pattern matching on the basename. The custom function runs for every file during tree rendering, so keep it efficient to avoid performance issues on large directories.

What is live filtering and how do I use it effectively?

Live filtering lets you type a search pattern that immediately filters the visible tree nodes as you type. Activate it with the default keybinding (usually /) while the tree is focused. The filter matches against file and directory names using Lua string matching. It is useful for quickly finding a specific file in a deep directory structure. Press Escape or the toggle key to clear the filter. For performance, the filter is applied incrementally rather than re-rendering the entire tree.

Can I customize the renderer to change how files and folders are displayed?

The renderer configuration offers extensive display customization. You can toggle indent markers, root folder labels, file icons, folder icons, and symlink indicators. The group_empty option collapses directories that contain only a single subdirectory. You can add trailing slashes to folders, highlight modified files, show git status in the highlight, and customize the icon set. Advanced customization is possible through the renderer.special_files and renderer.highlight_git options.

Neovim Plugin · Lua · Open Source

The Fastest Nvim Tree File Explorer for Neovim

Nvim Tree is a high-performance, Lua-native file explorer that renders your project directory as an interactive sidebar tree. It provides git status integration, live filtering, file operations, and deep customization — all without the overhead of legacy Vimscript plugins.

Lua Native

Sub-millisecond Render

Git Integration

Download Source Read the Guide

nvim-tree — ~/.config/nvim

▼ nvim

▸ lua

▸ plugins

📄 nvim-tree.luaM

📄 telescope.lua

📄 lspconfig.luaA

📄 init.lua

📄 .gitignore

📄 README.md

▸ ftplugin

▸ .git

require("nvim-tree").setup({
  sort = {
    sorter = "case_sensitive",
  },
  view = {
    width = 30,
  },
  renderer = {
    group_empty = true,
    highlight_git = true,
  },
  filters = {
    dotfiles = false,
  },
  git = {
    enable = true,
  },
})

NORMAL nvim-tree.lua lua · utf-8 · LF

Overview

A Complete File Explorer Built for Neovim

Nvim Tree replaces the need for external terminal file managers or legacy Vim plugins by delivering a fast, integrated tree view directly inside your Neovim editor. Written entirely in Lua, it leverages Neovim's async APIs and LuaJIT to scan, render, and update your project filesystem with minimal latency.

Unlike general-purpose file managers, Nvim Tree is purpose-built for the editing workflow. It understands git repositories, respects your project structure, and provides keybindings that feel native to Neovim's modal editing paradigm. The tree view opens as a sidebar buffer that coexists with your editing windows, letting you navigate files without leaving your keyboard.

Lua

Native implementation

0.8+

Minimum Neovim version

Git

Built-in status integration

100%

Open source & community driven

What Nvim Tree Gives You

Interactive sidebar file tree with real-time updates
Git status indicators on every file and folder
Create, rename, delete, move, and copy files from the tree
Live filtering with instant search as you type
Full keybinding customization with Lua API
Nerd Font icon support via nvim-web-devicons

Core Features

Everything You Need,
Nothing You Don't

Nvim Tree packs powerful features into a lean, fast package. No bloat, no unnecessary dependencies — just the tools that matter for navigating code.

Git Integration

Automatic git status detection for every file and directory. See staged, unstaged, untracked, and conflicted files at a glance with colored indicators — no external git plugin needed. Directories inherit the highest-priority status from their children, giving you an instant overview of your working tree health.

Built-in · Zero Config

Live Filtering

Type to instantly filter the tree. Matches update as you type using Lua string matching, making it fast to find files in deep structures.

File Operations

Create, rename, delete, cut, copy, and paste files and directories — all from keybindings without leaving the tree or opening a terminal.

How It Works

Three Steps to a Better Workflow

Install the Plugin

Add nvim-tree.lua to your plugin manager — lazy.nvim, packer.nvim, or manual installation into your Neovim runtime path.

Configure Your Setup

Call require('nvim-tree').setup{} in your init.lua with your preferred options for view, renderer, filters, and keybindings.

Navigate Effortlessly

Toggle the tree with a keybinding or command. Browse, open, and manage files — all without leaving your keyboard.

Why Nvim Tree

Benefits Over Traditional File Explorers

Nvim Tree isn't just another file tree — it's engineered specifically for the Neovim ecosystem with advantages that compound over time.

LuaJIT Performance

Written entirely in Lua with LuaJIT compilation. Renders large directories in sub-millisecond time, far outperforming Vimscript-based alternatives.

Native Neovim APIs

Uses Neovim's native async file system operations and buffer APIs. No shelling out to external commands for basic operations — everything runs in-process.

Zero Extra Dependencies

Git integration, file operations, and filtering all work out of the box. The only optional dependency is nvim-web-devicons for file type icons.

Deep Customization

Every aspect — from icons and colors to keybindings and filters — is configurable through a clean Lua API. Adapt the tree to match any workflow or theme.

Active Maintenance

Regular updates, bug fixes, and new features from a dedicated maintainer team. Tracks Neovim releases and adapts to API changes promptly.

Clean Architecture

Modular codebase with separated concerns — renderer, explorer, git, actions, and view are independent modules that are easy to understand and extend.

Use Cases

Built for Real-World Workflows

Full-Stack Web Development

Navigate between frontend components, backend routes, and config files across monorepo structures with hundreds of directories.

Systems & Embedded Programming

Browse C/C++ project trees with nested headers, source directories, and build system files. Git indicators show which files need attention.

Dotfile & Config Management

Manage Neovim, tmux, zsh, and other dotfiles from a single tree view. Quickly jump between plugin configs and shared modules.

Installation

Get Started in Minutes

Install with lazy.nvim (Recommended)

Add to your plugin spec. Set lazy=false so it loads at startup, and add nvim-web-devicons as a dependency for file icons.

{
  "nvim-tree/nvim-tree.lua",
  lazy = false,
  dependencies = {
    "nvim-tree/nvim-web-devicons",
  },
  config = function()
    require("nvim-tree").setup {}
  end,
}

Or Install with packer.nvim

If you're still on packer, use the use function with the same setup. Note: packer is in maintenance mode — consider migrating to lazy.nvim.

use {
  "nvim-tree/nvim-tree.lua",
  requires = {
    "nvim-tree/nvim-web-devicons",
  },
  config = function()
    require("nvim-tree").setup {}
  end,
}

Or Download ZIP for Manual Install

Download the source archive and extract it into your Neovim packages directory under pack/*/start/ for automatic loading.

~/.local/share/nvim/site/pack/nvim-tree/start/nvim-tree.lua

Download Nvim Tree Source

Get the complete source code as a ZIP archive from the official GitHub repository.

Format: ZIP Archive

Updated: Latest Master

License: MIT

Download ZIP

After downloading, place the extracted folder in your Neovim runtime path and add the setup call to your init.lua.
**Read the Full Guide**

Complete Guide

Master Nvim Tree Step by Step

Our comprehensive guide covers everything from basic setup to advanced Lua API usage. Each topic includes working configuration examples you can copy directly into your init.lua.

Installation with lazy.nvim, packer.nvim, and manual methods
Complete setup configuration reference
Keybinding customization and custom actions
Git integration deep dive and status indicators
Filter system — dotfiles, custom functions, live filtering
Renderer customization — icons, highlights, grouping
Lua API reference for programmatic control
Troubleshooting common issues and error fixes

Read the Full Guide

Why Read the Guide?

Most users only scratch the surface of Nvim Tree's capabilities. The guide walks you through every configuration option, explains the reasoning behind defaults, and shows you how to build a file explorer setup that matches your exact workflow. Whether you're a Neovim beginner or an experienced Lua developer, there's something valuable in every section.

Requirements

What You Need Before Installing

Editor

Neovim 0.8+

Minimum version for core functionality. Neovim 0.9+ recommended for full feature access and latest API improvements.

Language

Lua 5.1 (JIT)

Bundled with Neovim via LuaJIT. No separate Lua installation needed — everything runs through Neovim's built-in runtime.

Optional

Nerd Font

Required for file and folder icons. Install a Nerd Font (like JetBrainsMono Nerd Font) and configure your terminal to use it.

Workflow

How Nvim Tree Fits Your Editing Flow

Open the Tree

Toggle Nvim Tree with your configured keybinding or the :NvimTreeToggle command. The tree opens as a sidebar buffer without disrupting your current layout.

Browse and Filter

Navigate with j/k keys, expand directories with Enter or l, and press / to activate live filtering. Git status colors help you spot modified and new files instantly.

Open and Edit

Press Enter on a file to open it in the adjacent window. The tree can auto-close, stay open, or focus the new file — configure this behavior in actions.open_file.

Manage Files

Create new files with a, rename with r, delete with d — all from the tree. Changes reflect immediately without manual refresh. Use the trash option for safe deletion.

Common Mistakes

Avoid These Setup Pitfalls

Missing setup() call

Installing the plugin but forgetting to add require('nvim-tree').setup{} in init.lua. The plugin loads but uses all defaults and may not behave as expected.

Always add the setup call in your plugin config function, even if you're using default settings.

No Nerd Font installed

Icons appear as broken squares or question marks because the terminal doesn't have a font with the required glyph coverage for nvim-web-devicons.

Install a Nerd Font and set it as your terminal's font. JetBrainsMono Nerd Font is a popular choice.

Running multiple file explorers

Having NERDTree, telescope-file-browser, and Nvim Tree all active simultaneously causes keybinding conflicts and unpredictable buffer behavior.

Disable or remove all other file explorer plugins before setting up Nvim Tree.

Wrong install directory

Placing the plugin in the wrong runtimepath directory during manual install means Neovim can't find or load it on startup.

Use the exact path: ~/.local/share/nvim/site/pack/nvim-tree/start/nvim-tree.lua

Troubleshooting

Quick Fixes for Common Issues

Tree not showing up after installation

Cause: Plugin not in the correct runtimepath, setup call missing, or plugin not loaded by your plugin manager.

Run :checkhealth nvim-tree for diagnostics. Verify the plugin directory exists under your runtimepath. Confirm your setup call isn't wrapped in a conditional. Check plugin status with :Lazy or :PackerStatus.

File icons not displaying

Cause: nvim-web-devicons not installed, not loaded before Nvim Tree, or no Nerd Font configured in your terminal.

Install nvim-web-devicons and add it as a dependency. Install a Nerd Font and set it in your terminal emulator settings. Run :checkhealth nvim-web-devicons for details.

Slow performance on large repos

Cause: Scanning thousands of files with git status checks and no filters. node_modules, .git, and build directories add massive overhead.

Enable filesystem_watchers. Add node_modules, .git, dist, and build dirs to filters.exclude. Set git.ignore = true for non-git dirs. Enable renderer.group_empty to collapse single-child directories.

Keybinding conflicts with other plugins

Cause: Another plugin or your global keymaps use the same keys. Nvim Tree keybindings are buffer-local but can still conflict within the tree buffer.

Remap conflicting keys in view.mappings.list. Use the on_attach callback to set custom buffer-local keymaps that take highest priority. Disable default mappings with view.mappings.list = {} if needed.

Best Practices

Get the Most Out of Nvim Tree

Use lazy.nvim — It's the recommended plugin manager with better lazy-loading support, faster startup, and active development compared to packer.nvim.

Configure filters early — Set up filters.exclude for node_modules, .git, and other large directories before you start customizing appearance. This prevents slow renders on big projects.

Use on_attach for keymaps — The on_attach callback gives you buffer-local keymaps with the highest priority, avoiding conflicts with any other plugin or global mapping.

Enable filesystem watchers — For projects with frequent file changes, filesystem_watchers.enable = true provides instant tree updates without manual refresh.

Keep one file explorer — Remove NERDTree, vinegar, or other file browser plugins before setting up Nvim Tree to avoid buffer conflicts and keybinding clashes.

Run :checkhealth regularly — After Neovim or plugin updates, run :checkhealth nvim-tree to catch configuration issues, missing dependencies, or API changes early.

Advanced Tips

Power User Techniques

Lua API

Programmatic Tree Control

Use the Lua API to control Nvim Tree from autocommands, custom commands, or other plugins. Open the tree and find the current file automatically.

local api = require("nvim-tree.api") vim.api.nvim_create_autocmd("BufEnter", { callback = function() api.tree.find_file({ open = true }) end, })

Custom Filter

Hide Files by Size or Pattern

Write a custom Lua filter function to hide files matching complex criteria — large files, specific extensions, or files in certain paths.

filters = { custom = function(path) local basename = vim.fn.fnamemodify(path, ":t") return basename:match("%.min%.") or basename:match("%.map$") end, }

Custom Action

Open in External App

Create a custom keybinding action that opens the selected file in an external application — useful for images, PDFs, or logs.

{ key = "o", action = function(node) vim.fn.system("xdg-open " .. vim.fn.shellescape(node.absolute_path)) end, }

Performance

Optimize for Monorepos

Combine multiple optimization settings for large repositories with many subdirectories and files to keep the tree responsive.

filesystem_watchers = { enable = true } renderer = { group_empty = true } filters = { exclude = { "node_modules", ".git", "dist", "build", "__pycache__" }, } git = { ignore = true }

FAQs

Frequently Asked Questions

What is Nvim Tree and why should I use it?

Nvim Tree is a file explorer plugin for Neovim written entirely in Lua. It provides a sidebar tree view of your project filesystem with features like git status indicators, live filtering, file operations, and extensive keybinding customization. It offers significantly better performance than legacy Vim file explorers, native Neovim integration through Lua, and a highly customizable interface.

How does Nvim Tree differ from NERDTree?

Nvim Tree is written in Lua for Neovim, while NERDTree is Vimscript for Vim. Nvim Tree offers faster rendering through LuaJIT, native async operations, built-in git integration, live filtering, and a modern API. NERDTree has more extensions but lacks native performance and tight Neovim integration.

Is Nvim Tree actively maintained?

Yes, with regular updates, bug fixes, and new features. The repository receives consistent contributions and tracks Neovim releases, ensuring compatibility with latest stable and nightly versions.

What version of Neovim do I need?

Neovim 0.8 or later is required. For the best experience with all features, Neovim 0.9 or the latest stable release is recommended. Some advanced Lua API functions may require 0.9+.

Can I use Nvim Tree alongside other file explorer plugins?

Not recommended. Running multiple file explorers causes keybinding conflicts, redundant buffer management, and unpredictable behavior. Disable NERDTree, nvim-tree.lua forks, or telescope-file-browser when using Nvim Tree.

How do I install Nvim Tree with lazy.nvim?

Add 'nvim-tree/nvim-tree.lua' with lazy=false, add nvim-web-devicons as a dependency, and call require('nvim-tree').setup{} in the config function.

Can I download Nvim Tree as a ZIP file?

Yes, download the source as a ZIP from GitHub. Extract and place the nvim-tree.lua directory inside pack/*/start/ for automatic loading.

File icons are not displaying. How do I fix this?

Install nvim-web-devicons and ensure it loads before Nvim Tree. Verify a Nerd Font is installed and configured in your terminal. Run :checkhealth nvim-web-devicons for diagnostics.

Ready to Transform Your Neovim Workflow?

Download Nvim Tree now and experience the fastest file explorer built for Neovim. Free, open source, and actively maintained.

Download Source Read the Full Guide