vim-floaterm: a floating terminal held on one ring, with no releases to pin
:computer: Terminal manager for (neo)vim
At a glance
- What is it?
- A Vim script plugin that wraps Vim or Neovim terminals in a floating or popup window, keeps every instance on a single double-circular-linkedlist, and ships no tagged release for its three one line install snippets to pin to.
- Who is it for?
- Judged as a wrapper rather than a terminal emulator, vim-floaterm does a small job with an unusually wide command surface, and the details worth checking before you map anything onto it are all in the same file.
- 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 9 days ago.
- What is it written in?
- Mainly Vim Script, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 22, 2026, and from our analysis. They are not legal advice.
Star history
- voldikss/vim-floaterm2,660 ★ · +0
| Repository | 2026-10-04 | 2026-11-22 |
|---|---|---|
| voldikss/vim-floaterm | 2.7k | 2.7k |
0 Stars in the last 49 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Two window mechanisms sit behind the same command
The stated requirement is one line: Vim or neovim with the terminal feature. Everything about where the window lands depends on which editor runs it. The feature list states support for neovim floatwin and vim8 popupwin, so a neovim instance is a floatwin and a Vim 8 instance is a popupwin, and the plugin presents the two as one capability even though they are different window mechanisms sitting in different window systems. Its opening line covers both editors at once with the phrase floating/popup window, and customizable terminal window style is listed without saying which mechanism each editor gets. Neither the requirement line nor the feature list names a version floor for either editor, even though the popupwin path is spelled vim8 and the floatwin path is spelled neovim, so the two halves of that one requirement rest on different window systems arriving at different times. The only place the difference becomes a setting is the wintype option, which the command list forwards to g:floaterm_wintype, and the worked example passes --wintype=float explicitly. So a Vim 8 user has a global default deciding whether the window is a popup, and the legal values for that global appear only inside an example line rather than in a table.
:FloatermNew --height=0.6 --width=0.4 --wintype=float --name=floaterm1 --position=topleft --autoclose=always ranger --cmd="cd ~"That single line also carries the shape of the whole command: five options before the program name, a corner chosen with --position, a lifecycle value chosen with --autoclose, and a trailing argument forwarded to the program, which here is ranger with its own --cmd passed straight through.
Every instance joins one double-circular-linkedlist
Open several floaterms and they are attached to a double-circular-linkedlist, so navigation is a walk around a ring rather than a lookup by name. FloatermNext and FloatermPrev step one node in each direction, and FloatermFirst and FloatermLast jump to the two ends. No listing command and no per-buffer grouping appear among the commands documented here, so the way to reach a particular terminal is to know its name or its buffer number and type it into one of the addressable commands. The ring also decides what the bang forms do. FloatermShow! shows every floaterm, and the file states the limit directly: if multiple floaterms have the same position attribute, only one of them will be show. Position is a per instance option that itself forwards to g:floaterm_position, which means two instances created in the same corner overlap by design and the show all form quietly drops one of them. That sentence is the only place the overlap is mentioned, and the grammar error inside it is in the source.
Two lifecycle flags are documented and the third is forwarded to a global
Lifecycle is spread across three of the fourteen FloatermNew options, and they compose. The silent flag spawns a floaterm but does not open the window, leaving it for a later toggle. The disposable flag destroys the floaterm once it is hidden, which turns the buffer into something that exists only while it is visible. Autoclose is the odd one out: its entry does not explain anything and forwards to g:floaterm_autoclose instead, and the two worked examples are the only place its values appear, with always in the ranger line and never in the gcc line. Knowing that split before mapping keys onto these options matters, because an option list that describes two flags in prose and hands the third to a global is not a complete description of when a window opens or closes. Resizing is a separate command, FloatermUpdate, which takes the same options as FloatermNew except silent, and applies the change to every instance when given a bang.
Ten of the fourteen FloatermNew options point at a global instead of a value
Counting the option list under FloatermNew makes the shape obvious. Four entries explain themselves: cwd, name, silent, and disposable. The other ten, title, width, height, opener, wintype, position, autoclose, autoinsert, borderchars, and titleposition, do not. Each ends with see g:floaterm_something and moves the question to a different file, which is a reasonable choice for a plugin with this many knobs and a poor one for anyone reading the command list as reference. The table of contents at the top of the file promises a dedicated Options section, so the values belong there, but the body of the file reaches the FloatermSend entry and stops, and those globals never appear in it. What the command list does supply is the syntax: options are formed as --key[=value], completion is on TAB, and four separate commands accept the same grammar, so the per instance override and the global default are one mechanism rather than two. Those four are Toggle, Show, Hide, and Kill, and each takes the same optional target, either a buffer number or a name, with the file adding that for exactly those commands the name can also be written as a --name option.
cwd resolves two computed literals beside an ordinary path
Cwd is the most capable of the four documented options because it resolves more than a string. It accepts a path, the literal root which represents the project root directory, the literal buffer which specifies the directory of the active buffer, and the literal buffer-root which corresponds to the project root directory of the active buffer. One option therefore covers four directories, two of them computed when the floaterm opens from whichever buffer happens to be active, which is also a way to send two instances to different directories from the same keymap. The escape rules are where this turns sharp. Passing a space means a backslash followed by a space, and the backslash itself has to be typed twice. Command line special characters such as percent and cfile are auto-expanded to match builtin :terminal, so a literal one needs a backslash in front of it. A pipe is absorbed as an argument of the command, which is why it cannot be followed by another Vim command, while a && chain is fine.
:FloatermNew --autoclose=never gcc % -o %< && ./%<The filename placeholders expand to the current file and the line above it, and the chain survives the argument parsing even though a single pipe would not.
Two examples carry a space after the colon, and one link names a heading the contents omit
Copying a command out of this file does not always reproduce it. Two examples are written with a space between the colon and the command name: switching to the previous instance is given as colon space FloatermPrev, and the shell form of the open command as colon space FloatermNew! python, while the same file writes FloatermNext, FloatermFirst, FloatermLast, FloatermUpdate, FloatermToggle, FloatermShow, FloatermHide, FloatermKill and FloatermSend without that space everywhere else. The instruction covering the pair tells the reader to try both forms to learn the difference, so the stray space sits inside the one line a newcomer copies first. There is a second mismatch of the same kind. The range example, where a visual selection is sent into the created floaterm by prefixing the command with the marks for the selection, points the reader to a python repl use case, but no python entry appears in the table of contents, which lists Features, Requirements, Installation, Get started with its subpages, Advanced Topics, Contributing, FAQ, Breaking changes, Related projects, Credits and License.
Three install snippets, no releases, and a Breaking changes heading with no changelog file
Installation is offered three ways and each is one line: use for packer.nvim, Plug for vim-plug, and a call to dein#add for dein.nvim, all naming the same repository. Not one of them pins a commit, a branch, or a version, and the project has no GitHub releases, so there is nothing in its own distribution history to pin against. Every snippet therefore follows the default branch, which is master. The same gap shows up elsewhere: the table of contents lists a Breaking changes section, while the files tracked at the root hold no changelog, so breaking changes live as prose inside the README or nowhere at all. The badge row points at the GitHub Actions query for a workflow named CI, at the LICENSE file as it sits on master, and at the commit activity graph, which is the closest thing to a version signal a visitor is given. The last push on the default branch is dated 2026-08-29, recent enough to read as current work, but a plugin manager pulling master will absorb whatever lands next.
Vim script autoload files sit next to a lua directory and a tracked test directory
The repository tracks nine top level entries: .github, .gitignore, LICENSE, README.md, autoload, bin, doc, lua, plugin, and test. The language is filed as Vim script, and autoload plus plugin are where Vim script belongs, but a lua directory sits beside them, which is the LuaJIT side that neovim provides and plain Vim does not. Bin and test at the root complete a layout that has to hold up under both editors, with the tests kept in the repository rather than outside it. The file is equally direct about what should not run in the window: its note on long running jobs says that something like yarn watch inside the builtin terminal would slow the editor down and recommends external terminals instead, which is a real constraint of running work in Vim's own terminal buffer. The plugin still meets outside tools by name, listing ranger, fzf, and ripgrep for use from the command line, naming asynctasks.vim and asyncrun.vim as task runners it can back, and naming denite.nvim and fzf for switching and previewing between floating buffers.
Editorial conclusion
Judged as a wrapper rather than a terminal emulator, vim-floaterm does a small job with an unusually wide command surface, and the details worth checking before you map anything onto it are all in the same file. Ten of the fourteen FloatermNew options forward to globals you will have to look up separately, show-all drops an instance whenever two share a position, long running jobs belong in an external terminal by the project's own advice, and there is no tagged release, and the three install snippets track master unless you pin a commit and breaking changes live as prose with no changelog file at the root. Use it if your editor already has the terminal feature and you want a named, toggleable terminal per project. Pin a tested commit if reproducible installation matters, and assess whether its terminal listing and job handling fit your workflow.
Frequently asked questions
What does vim-floaterm need from the editor?
Vim or neovim with the terminal feature, which is the whole of the Requirements section in this file. The feature list adds that it supports neovim floatwin and vim8 popupwin, so the window mechanism differs by editor while the terminal underneath is Vim's own.
How do I open a vim-floaterm instance and find it again?
Use the FloatermNew command, whose options are formed as --key[=value] with completion on TAB. Give it the bang and the command runs in your shell instead of being run directly, and with no command at all it opens the shell. Afterwards you address an instance by its buffer number, by its name, or by a name passed as --name, and a bang applies the command to every instance.
Where do I get vim-floaterm, and can I pin a version?
Three one line snippets are offered, for packer.nvim, vim-plug, and dein.nvim, and none of them pins a commit, branch, or version. The repository has no GitHub releases either, so there is no tag to constrain, and all three snippets follow the default branch, which is master.
Why does vim-floaterm warn against long running jobs in its window?
Its note says that long running jobs such as yarn watch inside the builtin terminal would slow down your operation, and recommends putting them into external terminals instead. The plugin still works with outside tools by name: ranger, fzf, and ripgrep are listed for command line use, and denite.nvim and fzf for switching between floating buffers.
Can vim-floaterm open my shell instead of the command I typed?
Yes. With the bang on FloatermNew the command is executed in your shell variable rather than directly, and with no command given at all the shell is opened. The file asks the reader to try the two forms side by side to see the difference, writing one of them with a stray space after the colon.
What does vim-floaterm do with a visual selection?
Run the open command over a range and the selected lines are sent to the created floaterm, which the file illustrates with a python repl case and a C compile case that expands the current file and the line above it. The anchor for that python case does not appear in the file's own table of contents.
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/voldikss-vim-floaterm)Star history chart for your README
[](https://hysenlabs.com/projects/voldikss-vim-floaterm)Was this useful?