oil.nvim: editing the filesystem as a Neovim buffer

The problem oil.nvim solves: filesystem changes without leaving the buffer model

Most Neovim file explorers give you a tree and a set of keybindings that create, rename and delete files. oil.nvim takes the opposite route. It presents a directory as a normal buffer, and the edits you make to that buffer are the filesystem operations. Creating a file means adding a line. Renaming means changing the text of a line. Deleting means removing a line. Nothing happens on disk until you write the buffer, and the README is explicit about that: "Remember to `:w` when you're done to actually perform the actions."

The audience is narrow and specific. It is for people who already treat Neovim buffers as the primary interface to everything, and who find a modal tree panel to be a second, redundant interface. The README positions it as "a vim-vinegar like file explorer", which is the right lineage: vim-vinegar let you browse with the same buffer you were already editing. oil.nvim extends that idea from navigation to mutation. If you have never been comfortable with the idea that a directory listing is text, the plugin will feel like a trick rather than a tool.

How the buffer-to-filesystem mechanism actually works

oil.nvim takes over directory buffers by default. The setup option `default_file_explorer = true` means that editing a directory, whether through `vim .`, `:edit src/`, or `:Oil <path>`, opens an oil buffer instead of netrw. That is a deliberate interception, and the README notes you can set it to false if you want another plugin to handle directories.

The buffer itself is generated. The `columns` option controls what appears on each line, with `icon` on by default and `permissions`, `size` and `mtime` available but commented out. The documentation for the column system lives in `:help oil-columns`, and the README says the id is added at the beginning and the name at the end. So the editable region is the name, and the rest is decoration. That distinction is enforced at the cursor level: `constrain_cursor` defaults to `"editable"`, which keeps the cursor out of the parts of the line you cannot meaningfully change. Setting it to `"name"` narrows that further.

Applying changes is where the design gets interesting. The plugin does not simply diff the buffer and run shell commands. It has an LSP integration layer, configured under `lsp_file_methods`, with `enabled = true` by default and a `timeout_ms` of 1000. When you rename a file, the plugin can notify language servers so that imports and references elsewhere in the project follow the rename. The README describes `autosave_changes` as controlling whether buffers updated by `willRenameFiles` are saved automatically, and it accepts `false`, `true`, or the string `"unmodified"`. That is a real distinction from a plain shell `mv`, which leaves every open buffer pointing at a path that no longer exists.

There is also a cleanup path. `cleanup_delay_ms` defaults to 2000, and the README says oil will automatically delete hidden buffers after that delay, that setting it to false disables cleanup entirely, and that the cleanup process only starts when none of the oil buffers are currently displayed. That last clause matters more than it looks: it means an oil buffer you have backgrounded will not have its stale sibling buffers swept while it is still on screen.

Installing oil.nvim and making a first real change

The requirement is Neovim 0.10 or newer. The README points older versions at an nvim-0.x branch rather than promising compatibility. An icon provider is optional: mini.icons for file and folder icons, or nvim-web-devicons for file icons.

With lazy.nvim, the README gives this spec. Note the comment in the README that lazy loading is not recommended, because it is very tricky to make work correctly in all situations. If you copy this, keep `lazy = false`.

{
  'stevearc/oil.nvim',
  ---@module 'oil'
  ---@type oil.SetupOpts
  opts = {},
  dependencies = { { "nvim-mini/mini.icons", opts = {} } },
  lazy = false,
}

If you are not using a plugin manager, the README also documents a plain clone into the Neovim native package directory.

git clone --depth=1 https://github.com/stevearc/oil.nvim.git \
  "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/oil/start/oil.nvim

Either way, the setup call is the same one line. Put it in your init.lua.

require("oil").setup()

Now open a directory. Running `nvim .` should give you a buffer listing the current directory, not a netrw tree. Move the cursor to a filename, press `<CR>` to open it, and `-` to go up a directory. To make `-` work from a file buffer the way vim-vinegar does, the README suggests this keymap, which opens the parent directory of the current file.

vim.keymap.set("n", "-", "<CMD>Oil<CR>", { desc = "Open parent directory" })

The first real exercise is a rename. Open an oil buffer, change a filename on its line, and write with `:w`. The README's default options include `prompt_save_on_select_new_entry = true`, which means selecting a new, moved or renamed entry will prompt you to save first. If you want to skip the confirmation popup for simple operations, `skip_confirm_for_simple_edits` exists and defaults to false. Leave it false until you have watched the prompt fire a few times; it is the only thing standing between a stray keystroke and a rename on disk. For a floating window instead of a full buffer, the README documents `:Oil --float <path>`.

Where oil.nvim is the wrong tool

The buffer model is the whole point, and it is also the main limitation. A directory listing in a buffer is modal, transient, and tied to a window. If your working style depends on a persistent sidebar that stays visible while you edit, oil.nvim does not provide one. Opening it is an action; closing it is an action. The `buf_options` defaults set `buflisted = false` and `bufhidden = "hide"`, which keeps oil buffers out of your buffer list and hides rather than wipes them, but that is housekeeping, not a sidebar.

The second limitation is that nothing is applied until you write. That is a safety property, and it is also a failure mode. If you edit a listing, get distracted, and later run `:wa` out of habit, you apply a filesystem change you had half forgotten about. The confirmation prompt covers the simple cases, and `prompt_save_on_select_new_entry` covers selecting a changed entry, but the underlying model still assumes you are paying attention to which buffer you are writing.

Third, the LSP integration has a timeout, and the default is short. `lsp_file_methods.timeout_ms` is 1000, described in the README as the time to wait for LSP file operations to complete before skipping. On a large project with a slow language server, renames will proceed without the language server being updated. The README does not document a rollback path for a rename that was applied but not propagated.

Finally, `default_file_explorer = true` is an interception. If you have muscle memory built around netrw, or another plugin that expects to own directory buffers, oil.nvim will take that over and you will need to set the option to false and decide which plugin wins.

oil.nvim compared with a tree explorer and with a terminal file manager

The most common comparison is with a tree-style explorer such as neo-tree. The difference is not cosmetic. A tree explorer is a separate view that observes the filesystem and issues commands against it through its own keybindings. oil.nvim is a buffer that represents the filesystem and whose text is the command. In a tree explorer, renaming is an operation you invoke. In oil.nvim, renaming is an edit you make and then commit. The practical consequence is that oil.nvim inherits everything Neovim does to text: undo, search, visual selection, macros. You can rename ten files by selecting ten lines and editing them as a block. A tree explorer gives you a rename command and you run it ten times.

That same inheritance is why oil.nvim is a poor fit for anyone who wants a file manager to be a distinct mode. If you want a panel that behaves like a panel, the buffer model is friction rather than power.

The other comparison is with terminal file managers such as yazi, which run outside Neovim entirely and hand files back to your editor. That is a different architecture with a different cost: you leave the editor, and the integration back into open buffers is something you have to arrange. oil.nvim's LSP-aware rename is the specific thing you would lose by moving to an external manager, and it is the feature that most justifies staying inside Neovim. The README does not claim parity with any of these tools, and it should not be read as doing so.

Maintenance, upgrade cost and the MIT licence

The repository is not archived, and the last push was on 2026-06-02. The most recent release listed is v2.16.0 from 2026-05-24, following v2.15.0 in February 2025 and v2.14.0 in December 2024. The gap between v2.14.0 and v2.15.0 was roughly two months, and the gap between v2.15.0 and v2.16.0 was roughly fifteen months. That is not a steady release cadence, and anyone planning around a predictable upgrade schedule should note it. It is also not abandonment: the repository has a CHANGELOG.md, a doc directory, a test suite with run_tests.sh, and a Makefile whose `all` target generates docs, lints and runs tests.

The upgrade surface is the setup table. The README documents a large number of options, and several of them are behavioural rather than cosmetic: `default_file_explorer`, `delete_to_trash`, `cleanup_delay_ms`, `lsp_file_methods`, `watch_for_changes`. A change to the default of any of those changes what your config does without you touching it. Pinning to a tag and reading CHANGELOG.md before moving is the cheap insurance here.

The licence is MIT. That permits use, modification and redistribution with the licence and copyright notice retained. It does not grant trademark rights, and it comes with no warranty. If you are vendoring the plugin into a product or an internal distribution, the notice requirement is the part that actually creates work. This is a description of the licence text, not legal advice.

One maintenance detail worth knowing: the Makefile clones three helper repositories into the scripts directory (`nvim_doc_tools`, `nvim-typecheck-action`, `benchmark.nvim`) to run docs, typechecking and benchmarks. Contributing to this project means pulling in those tools, not just running the test script.

Editorial conclusion

Adopt oil.nvim if you already live in Neovim, want filesystem changes to go through buffer edits and :w, and are willing to read the confirmation prompt before pressing enter. Do not adopt it if you need a persistent sidebar tree, a preview pane, or a file manager that works outside Neovim. Before committing, verify that your Neovim is 0.10 or newer, then run :Oil in a scratch directory and watch which actions prompt for confirmation and which do not.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. stevearc/oil.nvim on GitHub