toggleterm.nvim
A Neovim plugin to persist and toggle multiple terminal windows with customizable layouts and commands.
What is toggleterm.nvim?
Toggleterm.nvim is a Neovim plugin that manages multiple persistent terminal windows within the editor. It allows users to create, toggle, and control terminals in various layouts like floating, vertical, horizontal, and tabbed, making terminal workflows more integrated and ergonomic. It solves the problem of Neovim's built-in terminal being functional but not ergonomic for running background processes or having multiple easy-to-access terminal sessions.
Neovim users (version 0.7 or newer) who frequently use terminal sessions within their editor for tasks like running background processes, version control, system monitoring, or executing commands without leaving the editing environment.
Developers choose toggleterm.nvim because it is a lightweight, reliable wrapper around Neovim's terminal functionality that prioritizes simplicity and persistent state without unnecessary complexity. Its unique selling points include persistent terminals across sessions, multiple layout orientations, and the ability to send commands directly from Neovim buffers to specific terminals.
Overview
A neovim lua plugin to help easily manage multiple terminal windows
Use Cases
Best For
- Managing multiple persistent terminal sessions (e.g., for long-running processes) within Neovim without losing state.
- Integrating terminal tools like lazygit or htop as custom, toggleable Neovim windows with tailored settings.
- Sending lines or visual selections from a Neovim buffer directly to a specific terminal for execution.
- Organizing terminal windows in flexible layouts (floating, vertical, horizontal, tabbed) to suit different workflow needs.
- Creating custom terminal commands or mappings for repetitive tasks (e.g., git operations) within Neovim.
- Toggling all open terminals at once or selecting a specific terminal from a list for focused control.
Not Ideal For
- Projects requiring tight integration with language-specific REPLs or advanced debugging tools, as the plugin explicitly avoids becoming a REPL solution.
- Users who need to have multiple terminals with different orientations (e.g., float and vertical) open simultaneously, since this is unsupported.
- Teams using Neovim versions older than 0.7, as compatibility is limited to v1.* tags with potentially reduced features.
- Developers seeking a plugin with extensive pre-built integrations or a large ecosystem of add-ons, due to the conservative, wrapper-focused philosophy.
Pros & Cons
Pros
Acts as a minimal wrapper around Neovim's terminal, avoiding bloat and focusing on reliability, as emphasized in its philosophy of not adding unnecessary complexity.
Supports multiple terminal orientations including float, vertical, horizontal, and tab, with configurability via size functions and float_opts for adaptive workflows.
Terminals retain state across toggles and sessions, enabled by persist_mode and hidden buffer settings, preventing data loss for long-running processes.
Allows creation of tailored terminals for tools like lazygit using the Terminal class with callbacks, making external utilities seamlessly toggleable within Neovim.
Cons
The plugin does not support having terminals with different directions open at once, restricting layout flexibility for complex multi-window setups.
Key features like winbar integration require Neovim nightly builds, making them unstable for standard installations and limiting immediate usability.
Setup involves numerous options and callbacks, with warnings against copy-pasting, which can lead to a steep initial tuning curve for optimal use.
Admits it won't evolve into a REPL plugin or add complex functionality, potentially lacking advanced job control or real-time collaboration tools.
Frequently Asked Questions
Related Projects
neotermWrapper of some vim/neovim's :terminal functions.
kitty-scrollback.nvim😽 Open your Kitty scrollback buffer with Neovim. Ameowzing!
FTerm.nvim:fire: No-nonsense floating terminal plugin for neovim :fire:
flatten.nvimPipe from wezterm, kitty, and neovim terminals into your current neovim instance. Like `code -r` on steroids.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.