akinsho /toggleterm.nvim

A neovim lua plugin to help easily manage multiple terminal windows

★ 5,622⑂ 206👁 21⑃ 193● 478▤ 12
LuaGPL-3.0Created 2020-08-17
Download: v2.13.1v2.13.1 ↓2.13.12024-12-30
-1
Daily
5,622
stars
206
forks
21
watchers
193
prs
478
issues
12
releases

README

toggleterm.nvim






A neovim plugin to persist and toggle multiple terminals during an editing session





!toggleterm in action



 Multiple orientations

- Float



!floating window



- Vertical



!vertical-terms



- Tab



!tab orientation



 Send commands to different terminals



!exec



 Winbar (Experimental/Nightly ONLY)







 Requirements

This plugin only works in _Neovim 0.7_ or newer.

 Installation

Using packer in lua

lua
use {"akinsho/toggleterm.nvim", tag = '', config = function()
  require("toggleterm").setup()
end}


Using lazy.nvim in lua

lua
{
  -- amongst your other plugins
  {'akinsho/toggleterm.nvim', version = "", config = true}
  -- or
  {'akinsho/toggleterm.nvim', version = "", opts = {--[[ things you want to change go here]]}}
}


Using vim-plug in vimscript

vim
Plug 'akinsho/toggleterm.nvim', {'tag' : ''}

lua require("toggleterm").setup()


You can/should specify a tag for the current major version of the plugin, to avoid breaking changes as this plugin evolves.
To use a version of this plugin compatible with nvim versions less than 0.7 please use the tag v1..

 Notices

- 28/07/1990 — If using persist_mode terminal mappings should be changed to use wincmd instead otherwise persist mode will not work correctly. See here for details.

 Why?

Neovim's terminal is a very cool, but not super ergonomic tool to use. I find that I often want to
set a process going and leave it to continue to run in the background. I don't need to see it all the time.
I just need to be able to refer back to it at intervals. I also sometimes want to create a new terminal and run a few commands.

Sometimes I want these side by side, and I _really_ want these terminals to be easy to access.
I also want my terminal to look different from non-terminal buffers, so I use winhighlight to darken them based on the Normal
background colour.

This is the exact use case this was designed for. If that's your use case this might work for you.

 Roadmap

All I really want this plugin to be is what I described above. A wrapper around the terminal functionality.

It basically (almost) does all that I need it to.

I won't be turning this into a REPL plugin or doing a bunch of complex stuff.
If you find any issues, _please_ consider a _pull request_ not an issue.
I'm also going to be pretty conservative about what I add.

 Setup

This plugin must be explicitly enabled by using require("toggleterm").setup{}

Setting the open_mapping key to use for toggling the terminal(s) will set up mappings for _normal_ mode. The open_mapping can be a key string or an array of key strings. 
If you prefix the mapping with a number that particular terminal will be opened. Otherwise if a prefix is not set, then the last toggled terminal will be opened. In case there are multiple terminals opened they'll all be closed, and on the next mapping key they'll be restored.

If you set the insert_mappings key to true, the mapping will also take effect in insert mode; similarly

Top issues

Latest release

v2.13.1 v2.13.1 2024-12-30
2.13.1 (2024-12-27)


 Bug Fixes

 check for terminal win before check if is valid (622) (22aefd4), closes 435

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON