# mikavilpas/yazi.nvim: running the yazi file manager inside a Neovim floating window

> yazi.nvim wraps the yazi terminal file manager in a Neovim floating window and keeps the two in sync. It is a good fit if you already live in Neovim and want file operations to respect open buffers and LSP state, and a poor fit if you want a standalone file manager or a drop-in netrw replacement without configuration.

**mikavilpas/yazi.nvim** — A Neovim Plugin for the yazi terminal file manager. This plugin allows you to open yazi in a floating window in Neovim.

- Repository: https://github.com/mikavilpas/yazi.nvim
- Stars: 1,877 · Forks: 59
- Language: Lua
- License: MIT
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/mikavilpas-yazi-nvim

## The gap yazi.nvim fills between yazi and Neovim buffers

Neovim's built-in netrw is a directory listing, not a file manager. yazi is a terminal file manager with its own navigation, selection and preview model. Running yazi in a separate terminal next to Neovim works until you rename a file: the buffer still points at the old path, and any LSP server attached to it now tracks a file that no longer exists.

yazi.nvim targets that specific seam. Its README describes the plugin as opening yazi in a floating window inside Neovim, with visible splits opened as yazi tabs. The intended user is someone who already has yazi installed and wants file operations to leave Neovim's buffer list and LSP attachments in a consistent state, rather than reconciling them by hand afterwards.

The plugin also covers the reverse direction. Files hovered in yazi are highlighted in Neovim, which the README frames as showing where you are relative to your Neovim session. That only applies to splits you currently have open, so the highlight is a partial map of your buffers, not a full project view.

## How the floating window, tabs and buffer sync actually work

The plugin is Lua, listed under lua/ and plugin/ in the repository, and it drives yazi as an external process rather than reimplementing it. The README states that when yazi opens, all visible Neovim splits become yazi tabs, so the window layout you already have is the navigation model inside the file manager.

Selection is where the design gets interesting. Selected files can be opened as the current buffer, a vertical split, a horizontal split, a new tab, or as quickfix items. If you have selected a file path in visual mode before opening yazi, the README says yazi opens that file instead of the current one. Multiple selections can be sent to the quickfix list in one action.

The sync behaviour is the part with real engineering behind it. The README states that files renamed, moved or deleted in yazi are kept in sync with open buffers, and also with currently running LSP servers; a technical explanation lives in documentation/for-developers/lsp-renaming.md. Buffer deletion uses a bundled version of snacks.bufdelete so the window layout survives, which the README says happens when files that are open are deleted in yazi. That is a deliberate choice: closing a buffer without collapsing splits avoids the layout scramble you get from a naive :bdelete.

Optional integrations are wired but not bundled. With telescope.nvim, fzf-lua.nvim or snacks.picker installed, <c-s> greps in the directory yazi is in, and if multiple files are selected the search is limited to those. With grug-far.nvim, <c-g> runs search and replace under the same selection rule. The README also mentions plugin management for yazi plugins and flavors, and a way to send custom commands to yazi.

## Installing yazi.nvim with lazy.nvim and opening a first file

The README lists three requirements before installation: Neovim stable or nightly, a recent version of yazi, and Windows 11 if you are on Windows. It also notes that opting into new features may require a recent yazi build, and points to documentation/installing-yazi-from-source.md for that case.

lazy.nvim is described as the preferred installation method. The README's example returns a LazySpec for "mikavilpas/yazi.nvim" with version = "*" for the latest stable release, event = "VeryLazy", and plenary.nvim as a lazy dependency. The keys block defines your own mappings; the README's example maps <leader>- in normal and visual mode to <cmd>Yazi<cr> for opening at the current file, and <leader>cw to <cmd>Yazi cwd<cr> for opening in Neovim's working directory.

```lua
---@type LazySpec
return {
  "mikavilpas/yazi.nvim",
  version = "*",
  event = "VeryLazy",
  dependencies = {
    { "nvim-lua/plenary.nvim", lazy = true },
  },
  keys = {
    { "<leader>-", mode = { "n", "v" }, "<cmd>Yazi<cr>", desc = "Open yazi at the current file" },
  },
}
```

After restarting Neovim, pressing the mapped key should open yazi in a floating window. Inside it, <f1> shows the keymap list, <c-v> opens selections in vertical splits, <c-x> in horizontal splits, <c-t> in new tabs, and <c-q> sends them to the quickfix list.

If you do not use a plugin manager, the README's fallback is to obtain yazi.nvim and its dependencies yourself, then map a key to require("yazi").yazi(). It also shows the recommended setup when open_for_directories is enabled: set vim.g.loaded_netrwPlugin = 1 and call require("yazi").setup({ open_for_directories = true }) inside a UIEnter autocmd.

```lua
vim.keymap.set("n", "<leader>-", function()
  require("yazi").yazi()
end)

vim.g.loaded_netrwPlugin = 1
vim.api.nvim_create_autocmd("UIEnter", {
  callback = function()
    require("yazi").setup({ open_for_directories = true })
  end,
})
```

Before any of that, run :checkhealth yazi. The README presents it as the way to see whether compatible versions are installed and working, which is a faster diagnostic than reading error output from a failed launch.

## Where yazi.nvim gets in your way

The dependency story is uneven. The README states that when you use lazy.nvim or rocks.nvim, yazi.nvim adds and lazy loads some minimal dependencies for you, and that if you use neither, you install the dependencies yourself. It points at lazy.lua for the list and at issue 306 for discussion. So the plugin's convenience is partly a property of your plugin manager, not of the plugin.

Platform support has a hard floor. Windows 11 is the minimum supported version on Windows, and the README does not describe a Windows 10 path. If your team is on Windows 10, this is not a plugin you can adopt and patch around.

Some features depend on tools that may not be present. Copying the relative path from the start file to the hovered file requires realpath on Linux and Windows, or grealpath on OSX. The grep and search-and-replace keybindings do nothing unless telescope, fzf-lua, snacks.picker or grug-far is installed, and the README explicitly says those integrations need separate installation. The buffer sync that closes buffers uses a bundled snacks.bufdelete, so that behaviour is not something you configure away.

Finally, yazi.nvim is not a file manager. It is a front end for one. If yazi is not installed or is too old, the plugin has nothing to drive, and the README's own advice is to check compatibility with :checkhealth yazi rather than expect the plugin to compensate.

## How yazi.nvim differs from oil.nvim and plain netrw

The closest alternative in practice is oil.nvim, which takes the opposite approach: instead of embedding a separate file manager process, it makes a directory editable as a Neovim buffer, so renames and moves are buffer edits that you apply. There is no floating window, no external binary and no yazi version to track. The trade-off is that you lose yazi's selection model, its previews and its own plugin ecosystem.

netrw, which ships with Neovim, is the other baseline. It requires no installation at all. It also has no concept of syncing renames with open buffers or running LSP servers, which is precisely the problem yazi.nvim exists to solve. If your file operations are rare and you do not mind manually reopening buffers afterwards, netrw costs you nothing and adds no dependency.

The choice between oil.nvim and yazi.nvim comes down to whether you want yazi itself. If you already use yazi in a terminal and know its keybindings, yazi.nvim preserves that muscle memory inside Neovim. If you have never used yazi, adopting yazi.nvim means adopting two tools, and the README's requirement of a recent yazi version is a version-tracking obligation that oil.nvim does not impose.

## Maintenance, releases and what the MIT licence means here

The repository is not archived, and the last push was on 2026-08-15. Releases are frequent and versioned: v14.0.0 and v13.9.1 both landed on 2026-08-15, with v13.9.0 before them on 2026-07-06. The presence of release-please-config.json and .release-please-manifest.json in the repository root is consistent with the automated release flow that produces those version bumps.

The README's lazy.nvim example uses version = "*", which the comment describes as the latest stable version. That is a moving target: a major version like v14.0.0 can change behaviour, and the jump from v13.9.1 to v14.0.0 on the same day suggests the project is willing to cut majors rather than accumulate minor changes. If you need reproducibility, pinning to a specific tag is the alternative, at the cost of manually tracking yazi compatibility.

Upgrade cost is mostly external. Because the plugin drives yazi, the README warns that opting into new features might require a recent version of yazi, and points to documentation/installing-yazi-from-source.md. Upgrading the plugin can therefore imply upgrading yazi, which is a second tool with its own release cadence.

The licence is MIT, which is permissive and permits commercial use and modification. The package.json in the repository root carries a separate ISC licence field for the JavaScript tooling, and its description notes the project was forked from DreamMaoMao/yazi.nvim; that metadata covers the tooling package, not the Lua plugin. This is a description of what the files say, not legal advice. If licence compatibility matters to your organisation, read LICENSE and package.json directly.

The repository also contains integration-tests/, spec/, .busted, selene.toml and .stylua.toml, which indicates the project runs its own test and lint tooling rather than relying on manual checks.

## Conclusion

Adopt yazi.nvim if you already run yazi and Neovim and want file renames, moves and deletes reflected in open buffers and running LSP servers. Skip it if you want a file manager that works without Neovim, or if you are on Windows 10, since the README states Windows 11 is the minimum supported version. Before committing, run :checkhealth yazi to confirm your yazi and Neovim versions are compatible, and check whether you use lazy.nvim or rocks.nvim, because without one of those the plugin's dependencies are yours to install.

## FAQ

### What is yazi used for?

yazi is a file manager for the terminal. In this plugin's case it is opened in a floating window inside Neovim, where its selection can be sent to buffers, splits, tabs or the quickfix list.

### Is YAZI secure?

The README makes no security claims about yazi or about yazi.nvim. What it does document is that the plugin copies relative paths using realpath or grealpath, and that it can send custom commands to yazi.

### How do I use Yazi over SSH?

The README does not cover SSH usage. It describes opening yazi in a floating window in Neovim, and notes that previewing images with yazi is covered in Yazi's own documentation related to Neovim.

### What are the hidden files in Yazi?

The README does not document hidden-file handling. The closest related feature it describes is opening yazi instead of netrw for directories, which is controlled by the open_for_directories option.

## Sources

- [Official README](https://github.com/mikavilpas/yazi.nvim#readme)
- [Project repository](https://github.com/mikavilpas/yazi.nvim)
- [Release notes](https://github.com/mikavilpas/yazi.nvim/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mikavilpas-yazi-nvim