oil.nvim: a directory view that is an ordinary buffer you have to write
Neovim file explorer: edit your filesystem like a buffer
At a glance
- What is it?
- oil.nvim turns a directory into a Neovim buffer, so moving, renaming and deleting files are normal edits that only happen on write. It reaches beyond the local filesystem through SSH and S3 adapters, and it deliberately does not lazily load.
- Who is it for?
- oil.nvim is for people who already live in Neovim and want file operations to feel like buffer edits rather than a modal dialog. It will not fit you if you want an explorer that lazy loads with your config.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 34 days ago.
- What is it written in?
- Mainly Lua, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.
Star history
- stevearc/oil.nvim6,980 ★ · +60
| Repository | 2026-09-23 | 2026-11-13 |
|---|---|---|
| stevearc/oil.nvim | 6.9k | 7k |
60 Stars in the last 51 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Nothing happens until you write the buffer
The central mechanic is that a directory view is a buffer of pending operations, not a live filesystem widget. You open a directory, and every change you make in that buffer is an instruction rather than an action: renaming a line, moving it, deleting it. `:w` is what actually performs them. That single rule is both the appeal and the surprise.
Adapters cross boundaries, so local and remote moves behave the same
Every filesystem interaction goes through an adapter, which is what lets oil work on more than a local directory as long as a destination has an adapter implementation. The documented consequence is that file operations work across adapters, so copying to and from a remote server over SSH uses the same buffer mechanics as copying between two local directories. SSH browsing uses a URL name template:
nvim oil-ssh://[username@]hostname[:port]/[path]That format is the one netrw uses, which is convenient if you are switching. S3 browsing needs a working `aws` setup and uses:
nvim oil-s3://[bucket]/[path]One wrinkle is specific to S3: older Neovim versions do not support numbers in a URL, so on Neovim 0.11 and earlier the S3 URL starts with `oil-sss`. Both adapters are for browsing and editing, and both have a floor you should read before relying on them.
The SSH adapter needs a shell and coreutils on the server
This is the limitation most likely to catch you out, because the adapter is the least forgiving part of the plugin. It does not support Windows machines, which rules out any host without a POSIX shell. It also requires the server to have a `/bin/sh` binary plus the standard Unix commands `ls`, `rm`, `mv`, `mkdir`, `chmod`, `cp`, `touch`, `ln` and `echo`. That is a short list, but on a minimal container image or a locked-down appliance you will find one or two of them missing. Before planning a workflow around browsing a production host over SSH, confirm those binaries are reachable as the account you will connect with.
Lazy loading is called out as very tricky, so it is turned off
The lazy.nvim configuration ships with `lazy = false` and a comment explaining that lazy loading is not recommended because it is very tricky to make it work correctly in all situations. That is unusual to state so plainly in a plugin spec, and it tells you something about how oil integrates. The plugin takes over directory buffers: with `default_file_explorer = true`, commands like `vim .` or `:e src/` open an oil view instead of whatever else would handle them. Set it to false and another plugin, netrw for instance, opens when you edit a directory. If you keep both oil and another explorer installed, that option decides who wins. Buffer-local and window-local options are part of the same picture: the view is configured as a buffer rather than as a special window, with `buf_options` carrying `buflisted = false` and `bufhidden = "hide"`, and `win_options` handling the window side. A hidden buffer can be re-entered later, which is convenient for a directory you keep coming back to and a source of confusion for a buffer you thought you had closed.
Neovim 0.10 is the floor, and older versions live on a separate branch
Requirements are short: Neovim 0.10 or newer, with a branch named `nvim-0.x` for older releases, and an icon provider if you want file and folder icons. Two providers are named, mini.icons for both files and folders, and nvim-web-devicons for file icons. Icons are the `icon` column in the default configuration, where `permissions`, `size` and `mtime` appear as commented-out alternatives, and you are expected to look up how to set them. The install section covers the usual plugin managers: lazy.nvim, Packer, Paq, vim-plug, dein, vim.pack for Neovim 0.12 and up, Pathogen, and the Neovim native package path. The minimum also rules out a class of setup: on an older Neovim you are installing from a branch that is not the default one. Pathogen and the native package path are the two routes that skip a plugin manager entirely, both a shallow clone into a directory the loader already scans:
git clone --depth=1 https://github.com/stevearc/oil.nvim.git \
"${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/oil/start/oil.nvimDevelopment happens against the same layout. A Makefile provides `test` for the suite through `run_tests.sh`, `lint` for LuaLS typechecking alongside luacheck and stylua, and a `profile` target that drives the LuaJIT profiler through `perf/bootstrap.lua` under `nvim --clean`. A separate `benchmark` target exists for opening a directory with many files, which is the scenario where a synchronous listing would be felt. The repository also carries `CHANGELOG.md`, which is where you check what a release actually changed rather than guessing from the version number.
Opening a view is one setup call and one command
The whole quick start is a single setup call in your init.lua:
require("oil").setup()Then open a directory with `nvim .`. `<CR>` opens the file or directory under the cursor and `-` goes up a directory, and any other change you make to the buffer is a pending operation until `:w`. If you prefer the vim-vinegar feel of a parent-directory keymap, add it yourself:
vim.keymap.set("n", "-", "<CMD>Oil<CR>", { desc = "Open parent directory" })Directories also open through `:edit <path>` or `:Oil <path>`, and `:Oil --float <path>` gives you the view in a floating window. The public API covers the same operations from Lua, including `get_cursor_entry()`, `discard_all_changes()`, `toggle_hidden()`, `set_columns()`, `set_sort()`, `select()`, `save()`, `open_float()` and `toggle_float()`.
Git status and diagnostics come from other people's plugins
The plugin stops short of decorating the view with repository state, and four extensions maintained by other authors fill that gap. oil-git-status.nvim from refractalize puts git status in the statuscolumn, so the colour comes from an existing column rather than from the buffer text. Two different projects named oil-git.nvim take the opposite approach: benomahony's version shows status with colour and symbols in the buffer, and malewicz1337's does it asynchronously with directory support. oil-lsp-diagnostics.nvim from JezerM adds diagnostics indicators as virtual text. The repository also ships recipes for pieces the core leaves out, including toggling the file detail view, showing the current working directory in the winbar, hiding gitignored files while showing git tracked hidden ones, and using the FreeDesktop trash on macOS instead of deleting outright. Choosing a trash recipe matters on a buffer whose whole purpose is deleting things.
Editorial conclusion
oil.nvim is for people who already live in Neovim and want file operations to feel like buffer edits rather than a modal dialog. It will not fit you if you want an explorer that lazy loads with your config. Before installing, check that your Neovim is 0.10 or newer, decide whether `default_file_explorer = true` should keep netrw out of the way, and read the SSH adapter's requirements if you plan to browse a remote host, since it needs a `/bin/sh` plus core Unix tools on the server and does not support Windows.
Frequently asked questions
How do I see hidden files in Neovim using the oil plugin?
The API exposes `toggle_hidden()` and `set_is_hidden_file(is_hidden_file)`, so a keymap can flip hidden file visibility on an oil buffer. A recipe for hiding gitignored files while showing git tracked hidden files is linked from the recipes list.
how to install oil nvim
With lazy.nvim, add the plugin spec with `opts = {}` and `lazy = false`, then call `require("oil").setup()` in your init.lua. Installation snippets are also given for Packer, Paq, vim-plug, dein, vim.pack on Neovim 0.12 or newer, Pathogen and the Neovim native package directory.
oil nvim vs netrw
netrw is the built-in explorer that oil replaces for directory buffers while `default_file_explorer` is true. The SSH adapter deliberately borrows the same URL form netrw uses, so the two are familiar in that respect, but oil treats a directory as a buffer whose edits apply on `:w` rather than acting immediately.
how to use oil nvim
Run `nvim .` to open a directory, use `<CR>` to open the entry under the cursor and `-` to go up. Make changes in the buffer and press `:w` to perform them; the API also offers `open_float()`, `select()`, `save()` and `discard_all_changes()` for scripting.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/stevearc-oil-nvim)Star history chart for your README
[](https://hysenlabs.com/projects/stevearc-oil-nvim)Was this useful?