Consult: search and navigation commands built on completing-read
:mag: consult.el - Search and navigate via completing-read
At a glance
- What is it?
- Consult is an Emacs Lisp package of search and navigation commands that all sit on top of the standard completing-read completion API, so it works with Vertico, Icomplete, the built-in completion or anything else that speaks that interface. It replaces switch-to-buffer with a command that can narrow across buffers, files, bookmarks and project roots, and it adds asynchronous grep and ripgrep.
- Who is it for?
- Consult suits an Emacs user who wants better search and navigation without committing to a particular completion stack, because it is compatible with Vertico, Icomplete and the built-in completion and keeps completion system specifics to a minimum. It does not suit someone who wants a single all-in-one setup without thinking about the pieces, since Consult is explicitly one component of a larger environment that pairs with Marginalia, Embark and Orderless.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 19 days ago.
- What is it written in?
- Mainly Emacs Lisp, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 23, 2026, and from our analysis. They are not legal advice.
Editorial analysis
Everything routes through completing-read
Consult provides search and navigation commands based on the Emacs completion function completing-read, documented in the Elisp manual. The package description in the README is short: useful commands built on completing-read.
That single design decision explains almost everything about the package. completing-read is the standard Emacs API for showing a list of candidates and letting the user filter them. By building on it rather than on a private minibuffer implementation, Consult inherits the behaviour of whatever completion system the user already has, and it works with the vertical completion packages that have become common in the Emacs world.
The compatibility list is specific: Consult is fully compatible with completion systems centred around the standard completing-read API, which includes Vertico, Mct, and the built-in default completion system and Icomplete. The package keeps the completion system specifics to a minimum, and the ability of the Consult commands to work well with arbitrary completion systems is described as one of the main advantages of the package.
The stated conclusion is that Consult fits well into existing setups and helps you create a full completion environment out of small and independent components. That is a deliberate position. A package that shipped its own minibuffer would work on its own terms and would not work with your settings; Consult does the opposite, which means more of your existing configuration carries over and fewer of its features are available out of the box.
The upstream README also records a philosophy of small and independent packages, and the complementarity argument is spelled out. Marginalia enriches the completion display with annotations such as documentation strings or file information. Embark provides local actions comparable to a context menu, operating on the selected candidate in the minibuffer or at point in normal buffers, for example offering to delete a file when selecting from a list of files, and it offers a facility to collect completion candidates in a collect buffer.
consult-buffer replaces switch-to-buffer with narrowing
The flagship command is consult-buffer, an enhanced version of switch-to-buffer with support for virtual buffers. It supports live preview of buffers and narrowing to the virtual buffer types.
The narrowing keys are the interesting part, because they are how one command covers what several built-in commands did.
b Buffers
SPC Hidden buffers
* Modified buffers
o Buffers from other frames/tabs
f Files (Requires recentf-mode)
r File and buffer registers
m Bookmarks
p Project
B Project buffers
F Project files
R Project rootsCustom sources can be configured in consult-buffer-sources. By default, buffers from all frames are taken into account, and the buffers considered can be customised through the variable consult-buffer-list-function.
There is also an ephemeral buffer mode. Pressing SPC shows ephemeral buffers, and typing f SPC narrows to recent files.
The rest of the buffer family follows the same shape. consult-buffer-other-window, consult-buffer-other-frame and consult-buffer-other-tab are variants of consult-buffer. consult-project-buffer is a variant restricted to buffers and recent files of the current project, with custom sources configurable through consult-project-buffer-sources, and it may prompt you for a project if you invoke it from outside one.
Then there are the simpler commands. consult-bookmark selects or creates a bookmark, supports preview of bookmarks and narrowing, and the documentation notes you might use consult-buffer as an alternative since it can include a bookmark virtual buffer source. consult-recent-file selects from recent files with preview, with recentf-mode enabling the tracking of recent files, and again consult-buffer can include recent files as a virtual buffer source.
Search, editing and the future history trick
Beyond buffers, the package covers search and editing.
On search, Consult offers asynchronous and interactive consult-grep and consult-ripgrep commands, and the line-based search command consult-line. The editing side includes consult-yank-pop, an enhanced version of yank to select an item from the kill-ring, plus consult-yank-from-kill-ring and consult-yank-replace, and consult-kmacro.
The repository layout shows the scope as a set of focused modules rather than one large file. There is consult.el as the main entry, and then separate files per area: consult-compile.el, consult-flymake.el, consult-imenu.el, consult-info.el, consult-kmacro.el, consult-org.el, consult-register.el and consult-xref.el. There is also NEWS.org for the changelog and README.org, which is the source of the Texinfo manual, since the README carries the Texinfo export headers for the manual and a table of contents set to headlines with a depth of 8.
One feature deserves calling out because it is small and much liked. Many Consult commands implement what the documentation calls a little known but convenient Emacs feature called future history, which guesses what input the user wants. At a command prompt, type M-n and typically Consult will insert the symbol or thing at point into the input.
Another one is consult-imenu, which the documentation gives as the example of an enhanced version of a built-in Emacs command, presenting a flat list of the Imenu with live preview, grouping and narrowing.
The commands follow a consistent naming scheme, consult-<thing>, which matters more than it sounds because of how you discover them. The documentation says that if you have Marginalia annotators activated, type M-x ^consult to see all Consult commands with their abbreviated description, and alternatively C-h a ^consult gives an overview of all Consult variables and functions with their descriptions.
Installation through the standard Emacs package archives
Consult is distributed through the usual Emacs package channels, and the README carries badges for each of them: GNU ELPA, GNU-devel ELPA, MELPA Releases and MELPA Snapshots, plus a GNU Emacs badge.
The choice between them matters in practice. GNU ELPA and GNU-devel ELPA are the archives associated with Emacs itself, with the devel version carrying packages that have not yet been accepted into the stable archive. MELPA is the community archive, with a releases channel and a snapshots channel. A package that is in MELPA Snapshots but not MELPA Releases is one that has not had a stable release cut.
The repository has no GitHub releases, so the archive is where the versions come from.
There is also a .elpaignore file at the repository root, which is the mechanism for excluding files from the package build. That matters for a package like this, where the repository contains development files that should not be shipped.
The source layout is otherwise minimal: consult.el plus the seven per-area modules, NEWS.org, README.org, the LICENSE, and the .github directory for the automation. There is no build system in the conventional sense, because there is nothing to build. Emacs Lisp is interpreted, and the package is loaded from source.
The licence field on the repository says GPL-3.0, and the LICENSE file is at the root. For a package distributed through the Emacs package archives, that is the conventional choice and the one that keeps the package eligible for those archives.
Where Consult is the wrong choice
There are two honest reasons to skip it.
The first is that it is a partial replacement. Consult does not include a completion system, an annotation system or an action system. The documentation is explicit that Consult fits well into existing setups and helps you create a full completion environment out of small and independent components, and it names Marginalia, Embark and Orderless as the complementary packages. If you want the finished environment rather than the components, the configuration work is on you, and the size of that work depends on which of the others you also install.
The second is that it shadows built-in commands, and the shadowing is deeper than a single binding. consult-buffer is an enhanced version of switch-to-buffer, and consult-imenu replaces the Imenu presentation. There are more in the same vein: consult-yank-pop is an enhanced version of yank, consult-line is a line-based search command, consult-grep and consult-ripgrep are the async and interactive search commands, and consult-info, consult-compile, consult-flymake, consult-kmacro, consult-org, consult-register and consult-xref each cover a built-in area.
That is the point of the package, but it means adopting it is a decision about your muscle memory as much as about your configuration. A user who has muscle memory for switch-to-buffer with a particular narrowing scheme has to relearn it.
The alternative approaches differ in how much they give up. The built-in completion and the built-in commands work everywhere with no configuration and no shadowing, at the cost of the live preview, the virtual buffer narrowing and the async search. A single all-in-one package, of which the Emacs world has a few, gives you the whole environment at once but couples you to one maintainer's configuration and one author's idea of how completion should look. Consult is the opposite bet: a small core that behaves the way your existing completion system already behaves, plus optional companions for the parts it deliberately leaves out.
For a user who already runs Vertico and wants better search and navigation, Consult is the smaller step. For a user who has never configured their completion and wants one package to do everything, it is the wrong starting point.
Editorial conclusion
Consult suits an Emacs user who wants better search and navigation without committing to a particular completion stack, because it is compatible with Vertico, Icomplete and the built-in completion and keeps completion system specifics to a minimum. It does not suit someone who wants a single all-in-one setup without thinking about the pieces, since Consult is explicitly one component of a larger environment that pairs with Marginalia, Embark and Orderless. Before adopting it, check that the command set does not collide with the bindings you already use, since it replaces built-in commands such as switch-to-buffer, and read the available-commands section to see which built-ins you will be shadowing.
Frequently asked questions
What does the Consult Emacs package do?
It provides search and navigation commands based on the Emacs completing-read function, including asynchronous and interactive consult-grep and consult-ripgrep, the line-based consult-line, and consult-buffer, an enhanced switch-to-buffer with virtual buffers, live preview and narrowing.
Which completion systems does Consult work with?
Consult is fully compatible with completion systems centred around the standard completing-read API, which includes Vertico, Mct, and the built-in default completion system and Icomplete. The package keeps completion system specifics to a minimum.
How do I narrow consult-buffer to a particular source?
The narrowing keys cover buffers with b, hidden buffers with SPC, modified buffers with *, buffers from other frames or tabs with o, files with f, registers with r, bookmarks with m, and project entries with p, B, F and R. Custom sources can be added through consult-buffer-sources.
Where can I install Consult from?
The README carries badges for GNU ELPA, GNU-devel ELPA, MELPA Releases and MELPA Snapshots, so all the standard Emacs package archives carry it. The repository itself has no GitHub releases, and the licence field says GPL-3.0 with a LICENSE file at the repository root.
How do I see all Consult commands and variables in Emacs?
The documentation says that with Marginalia annotators activated, typing M-x ^consult shows all Consult commands with their abbreviated description, and typing C-h a ^consult gives an overview of all Consult variables and functions with their descriptions.
Official sources
Was this useful?