Neovim Qt: a cross-platform GUI that wraps Neovim in a Qt6 window

A GUI that runs Neovim as a subprocess and communicates over msgpack-RPC

Neovim Qt gives Neovim a desktop window without replacing the editor. It launches a Neovim subprocess and exchanges messages with it over msgpack-RPC, which is Neovim's own remote API. Every keystroke and buffer change passes through that connection; Qt handles the window, the font engine and the rendering surface.

Written in C++ under the ISC licence, Neovim Qt runs on any platform Qt supports; v0.2.20 was released on 2026-08-26 and master was last pushed on 2026-09-26.

That subprocess model has a direct consequence. Neovim itself must be installed and findable on your PATH before Neovim Qt can start. If it is not present, the binary cannot launch. Passing `--nvim {path_to_nvim}` on the command line bypasses the PATH search and points the GUI at a specific binary. Running `nvim-qt --version` reports which nvim binary the GUI found, under the `nvim:` line in the Environment section, so a startup failure is diagnosable before looking anywhere else.

Neovim Qt is not a standalone editor and includes no editing engine of its own. There is no way to use it without Neovim installed. Any Neovim configuration, including plugins and colour schemes, applies in Neovim Qt without changes, because the same Neovim process handles all editing. This is a tool for existing Neovim users who want OS-level font selection, a scrollbar and proper desktop clipboard integration, without switching editors or relearning keybindings.

Installing on Windows, macOS and Linux with the system package manager

Packages exist for all three major platforms, and each platform uses its native installer.

On Windows, Neovim and Neovim Qt are separate packages and both are required:

winget install neovim.neovim
winget install equalsraf.neovim-qt

Running the second command without the first leaves no Neovim binary for the GUI to find, which produces an immediate startup error. On macOS, Homebrew carries Neovim Qt in its core repository. Two options are available: the stable Homebrew package and the development commits on master:

brew install neovim-qt

brew install --HEAD neovim-qt

The HEAD option installs directly from master and may include commits ahead of the last packaged version. On Linux, coverage depends on the distribution. Arch Linux provides the package in the Extra Repository:

sudo pacman -S neovim-qt

Debian and Ubuntu include it in their own repositories, and the README notes this also covers distributions built from those repositories such as Linux Mint:

apt install neovim-qt

Guix installs both Neovim and the GUI in one command:

guix install neovim-qt neovim

Gentoo has a community package in the GURU overlay, and OpenSUSE provides one through the community build service. Distributions not on this list may not carry a binary package; for those, building from source is the documented path, covered in a later section.

ginit.vim runs after init.vim, and that order decides where :Gui commands belong

Neovim Qt reads two configuration files in sequence. init.vim runs first, as it always does in Neovim. At that point the Qt GUI shim has not loaded yet, so any `:Gui` command placed there will either error or be silently ignored at startup.

ginit.vim runs next, after the shim is ready. Default file locations are:

- Windows: `%LOCALAPPDATA%\nvim\ginit.vim` - macOS: `~/.config/nvim/ginit.vim` - Linux: `~/.config/nvim/ginit.vim`

On macOS and Linux the file sits in the same directory as init.vim. On Windows, both files belong under `%LOCALAPPDATA%\nvim`.

Standard Vim options such as `:set guifont=...` can go in init.vim because Neovim Qt reads them directly. Anything prefixed with `:Gui`, including `:GuiTabline`, `:GuiPopupmenu` and `:GuiFont`, must go in ginit.vim. Moving these to the wrong file is a common setup mistake, and the project's FAQ addresses it directly: "These options must be configured from `ginit.vim`. The file should be placed in the same directory as `init.vim`."

For users migrating from a terminal Neovim setup, this means a new configuration file is required even if init.vim already contains font or display settings. The `:GuiTabline 0` line that disables the Qt tab bar, for example, must live in ginit.vim or it has no effect.

GuiFont, GuiTabline, GuiPopupmenu and GuiScrollBar each address one widget

Four commands control the GUI-specific parts of the window. The recommended template in the README checks for each command before calling it:

if exists(':GuiFont')
    GuiFont {font_name}:h{size}
endif

if exists(':GuiTabline')
    GuiTabline 0
endif

if exists(':GuiPopupmenu')
    GuiPopupmenu 0
endif

if exists(':GuiScrollBar')
    GuiScrollBar 1
endif

GuiFont takes a font name and size joined by a colon and the letter h. For example, `:GuiFont Fira Code:h12` sets Fira Code at 12 points. An equivalent option is `:set guifont=Hack:h12`, which uses the standard Vim guifont syntax.

A common font error is worth knowing about before trying custom fonts. Fonts with variable-width characters produce warnings such as "{Font Name} is not a fixed pitch Font" or "Warning: Font {Font Name} reports bad fixed pitch metrics". These appear for proportional fonts. Overriding them uses `:GuiFont! {Font Name}`, with an exclamation mark. The project FAQ notes these warnings are safe to ignore, but spacing and clipping issues may appear with fonts that trigger them.

GuiTabline switches the native Qt tab bar off or on. GuiPopupmenu chooses between the Qt-rendered popup and the TUI popup that terminal Neovim users expect. GuiScrollBar shows or hides the window scrollbar. The popup menu decision matters for users coming from terminal Neovim: the Qt menu is a desktop widget and looks different from the TUI version. Setting `:GuiPopupmenu 0` restores the terminal menu appearance. Right-click behaviour is separate and available through `GuiShowContextMenu()`, with keymaps given in the README for normal, insert, visual and select modes.

The runtime path controls whether :GuiFont and :GuiTabline are defined at all

Every `:Gui` command depends on the Neovim Qt runtime, a Vimscript shim that defines them. When the runtime is absent, those commands are undefined, and any setting in ginit.vim that calls them silently does nothing. No error message identifies the root cause directly, which makes the runtime check the first step when GUI settings have no visible effect.

Running `nvim-qt --version` shows what the binary found:

nvim-qt --version

In the output, look for the `runtime:` entry under the Environment section. A non-empty path pointing to a folder that contains `nvim_gui_shim.vim` means the runtime loaded successfully. An empty `runtime:` value means the shim is not loaded, and no `:Gui` command will work in that session.

Two fixes are documented for a missing runtime. Setting the `NVIM_QT_RUNTIME_PATH` environment variable points the binary to the runtime folder manually. Alternatively, installing the runtime as a Vim plugin works for setups where a plugin manager is already in use: `Plugin 'equalsraf/neovim-gui-shim`. This option suits installations where the runtime folder was not placed alongside the binary.

Distribution packages place the runtime in the expected location as part of the install. A build from source does not set the path automatically, which is why the build instructions include an explicit `NVIM_QT_RUNTIME_PATH` assignment as the final step.

Building from source uses cmake, and NVIM_QT_RUNTIME_PATH must be set by hand

A condensed build sequence uses cmake and is documented in the README:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build .
NVIM_QT_RUNTIME_PATH=../src/gui/runtime bin/nvim-qt

The last line sets `NVIM_QT_RUNTIME_PATH` to the runtime folder inside the source tree before launching the binary. Without that assignment, the binary starts but all `:Gui` commands are undefined, because cmake does not embed the runtime path into the compiled executable. A note in the README makes this explicit: "`NVIM_QT_RUNTIME_PATH` must be set for commands such as `:GuiFont` to work."

Full instructions covering dependencies and platform-specific steps are on the project Wiki rather than in the README. Repository structure includes CMakeLists.txt, a cmake folder, a bindings folder, a third-party folder and a test folder alongside the src directory. No dependency package names or minimum version requirements appear in the README; the Wiki is where those are documented.

For Linux users building from source, Qt version selection matters. Systems with both Qt5 and Qt6 installed may have cmake pick up the wrong version, and the two sets of libraries are not interchangeable. The repository description targets Qt6, so confirming which Qt cmake finds before the build step prevents a version mismatch that would be difficult to diagnose from the linker output alone.

The version example in the README shows Qt 5.15.2 but the project description targets Qt6

A discrepancy in the README is easy to miss on a first read. The file includes an example `nvim-qt --version` output as part of the FAQ on missing runtime commands:

NVIM-QT v0.2.16.1
Qt Version: 5.15.2

The repository description at the top of the project page reads "Neovim client library and GUI, in Qt6." Those two do not agree: the example comes from v0.2.16.1 (the current release is v0.2.20) and shows Qt 5.15.2, a Qt5 version, while the description names Qt6.

For troubleshooting, this matters. If a freshly installed binary reports Qt5 in its `nvim-qt --version` output and the current codebase targets Qt6, either the installed binary is old or cmake linked against Qt5 libraries during a from-source build. A current build should show a Qt6 version string in that field.

For distribution packages, this usually resolves itself because the package maintainer controls the Qt dependency. For source builds on a machine where Qt5 and Qt6 coexist, cmake may select Qt5 if not directed otherwise. The discrepancy also means the README's version example cannot be used to verify a correct Qt6 installation, since its output is from a build era before the Qt6 migration.

Editorial conclusion

Neovim Qt is a practical choice for Vim and Neovim users who want a native desktop window on Windows, macOS or Linux without abandoning their existing config or keybindings. Skip it when Neovim cannot be installed on the target machine, or when a self-contained editor with no subprocess dependency is required. Before putting it into daily use, run nvim-qt --version and confirm that the runtime: line under Environment points to a folder containing nvim_gui_shim.vim. Without that, GuiFont, GuiTabline and GuiPopupmenu are all undefined, and whatever ginit.vim you write has no effect on the window.

Frequently asked questions

Official sources

1. equalsraf/neovim-qt on GitHub
2. License: ISC
3. Project website
4. README
5. Releases