vim-floaterm: A Terminal Manager for (neo)vim Floating Windows

The problem vim-floaterm solves: many shells, one editor window

A terminal emulator and an editor are two windows, and switching between them costs a keystroke and a moment of context. Vim 8 and Neovim both ship a builtin :terminal, so the shell can live inside a buffer. The builtin terminal is a normal window, though. It takes screen space, it is awkward to hide and bring back, and a single terminal buffer cannot hold several independent sessions at once.

vim-floaterm wraps the builtin terminal in a floating or popup window and adds a manager on top. The README describes the scope plainly: use the (neo)vim terminal in a floating or popup window, manage multiple terminal instances, and customize the window style. The buffer's filetype is set to floaterm, which is the hook other plugins use to recognize it.

The people who get value from this are Vim users who already live inside the editor and want a shell that behaves like a panel: a REPL next to a Python file, a build watcher, a git prompt, each one a named instance. The README's own example is compiling and running C from the editor with :FloatermNew --autoclose=never gcc % -o %< && ./%<, where % and %< are expanded the way :terminal expands them.

How the instance list works, and why order is a linked list

Every terminal you open becomes an instance with attributes: a name, a working directory, a width and height, a window type, a position, and flags such as silent, disposable, autoclose and autoinsert. Those attributes can be set globally through g: variables or per instance through options on the command line, written as --key=value.

The README states that when you have opened multiple instances, they are attached to a double-circular-linkedlist. That is the detail worth noticing. A linked list means :FloatermNext and :FloatermPrev move through instances in the order you created them, and :FloatermFirst and :FloatermLast jump to the ends. There is no sorting by recency and no grouping by project. If you open a dozen terminals, the only handle you have on any of them is its position in that list or the name you gave it.

Commands accept a target in three forms: a buffer number as a range prefix, a floaterm name, or nothing, meaning the current instance. The same targeting applies to :FloatermToggle, :FloatermShow, :FloatermHide and :FloatermKill, and appending ! widens the command to every instance. :FloatermToggle with a name that does not exist creates a new instance with that name, which is a convenient shortcut and also an easy way to accumulate terminals you did not intend to open.

Installing vim-floaterm and opening a first terminal

The README lists one requirement: Vim or Neovim with the terminal feature. There is no build step and no external binary. Installation is whatever plugin manager you already use. With vim-plug, the README gives this line for your vimrc:

Plug 'voldikss/vim-floaterm'

With packer.nvim, the same plugin is declared in Lua:

use 'voldikss/vim-floaterm'

After restarting the editor, :FloatermNew opens a floaterm window running $SHELL. :FloatermToggle hides it and brings it back. The README notes that both commands support <TAB> completion for their arguments.

A first useful instance sets its own geometry and name rather than accepting the defaults. The README gives this example, which opens a float named floaterm1 in the top left corner running ranger:

:FloatermNew --height=0.6 --width=0.4 --wintype=float --name=floaterm1 --position=topleft --autoclose=always ranger --cmd="cd ~"

Two details bite when you write your own. First, to include a space inside an option value you must escape it, and the backslash itself must be doubled, so the README's rule is a backslash followed by a space, with the backslash typed as \\. Second, <bar> is treated as an argument of the command, so a floaterm command cannot be followed by another Vim command on the same line. If you want to start a shell without showing it, pass --silent and toggle it later; if you want the window to disappear for good when hidden, pass --disposable.

Where vim-floaterm is the wrong tool

The README carries a warning in bold: long-running jobs such as yarn watch inside the builtin terminal would probably slow down your operation, and it recommends putting them into external terminals. That is a direct limitation from the project itself, and it should decide the question for anyone whose main need is a persistent background process. A watcher, a dev server, a long test run: the README tells you to keep those outside.

The instance model has its own friction. There is no documented way to search instances by working directory, and the linked list order is the only sequence you get. :FloatermUpdate can change height, width and the other window attributes after the fact, and with ! it applies the update to every instance, but the README does not describe changing an instance's name or its working directory once it exists. The README also does not document rollback, migration between plugin managers, or what happens to running jobs when an instance is killed rather than hidden.

Finally, the project's maintenance signal is weak. The repository is not archived, but the last push was on 2026-08-29, and no recent releases were retrieved. If you need a plugin with a release cadence you can plan around, this is not it.

vim-floaterm versus toggleterm.nvim and the builtin :terminal

toggleterm.nvim is the closest alternative, and the difference is not cosmetic. toggleterm.nvim is a Lua plugin for Neovim, so it does not run on Vim 8 at all. vim-floaterm is written in Vim Script and supports both Neovim floatwin and Vim 8 popupwin, which is the reason to pick it if your configuration has to work in both editors or if you are on Vim 8. On pure Neovim, toggleterm.nvim is the more natural fit for a Lua-based config.

The builtin :terminal is the other comparison, and vim-floaterm is best understood as a manager layered on it. The README says :FloatermNew shares consistent behavior with the builtin command, including expansion of cmdline-special characters such as % and <cfile>. What it adds is the window and the instance list. If you only ever need one shell and you do not mind it occupying a split, the builtin terminal already does that job and you avoid a dependency.

vim-floaterm also has an integration surface the alternatives approach differently. The README documents using it with external tools like ranger, fzf and ripgrep, using it as a task runner for asynctasks.vim or asyncrun.vim, and writing sources so fuzzy finders such as denite.nvim or fzf can switch and preview terminal buffers. That last point is the real differentiator: the plugin exposes enough structure for a fuzzy finder to treat terminals as selectable items.

Licence and what an upgrade actually costs

vim-floaterm is MIT licensed, and the LICENSE file sits at the repository root. For most users that means the plugin can be bundled, modified and redistributed with the copyright notice and permission notice intact. This is a description of the licence text, not legal advice; if you are shipping the plugin inside a product, read the LICENSE file and talk to whoever handles licensing for you.

Upgrade cost is where the missing release history matters. No recent releases were retrieved, so there is no changelog to read before pulling a new commit. The README has a Breaking changes section in its table of contents, which is the place to look when a command stops behaving as you expect, but the README text available here does not include its contents. In practice you are tracking the master branch through your plugin manager, which means an upgrade is a pull and a restart, and the way to find out what changed is that section plus the commit history.

Because the plugin is Vim Script plus a lua/ directory, there is nothing to compile and no runtime dependency to reconcile. The upgrade risk is behavioral rather than structural: command options, default window attributes, and the g: variables that back them.

Editorial conclusion

vim-floaterm suits Vim 8 and Neovim users who want several named terminals and are willing to drive them from Ex commands; it is the wrong choice if you need a build that is currently maintained, since the last push was on 2026-08-29 and the README does not document rollback or upgrade steps. Before adopting it, check that your Vim or Neovim was built with the terminal feature, because the README lists that as the only requirement.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. voldikss/vim-floaterm on GitHub