abo-abo/swiper: Ivy, Counsel and Swiper for Emacs minibuffer completion

What Ivy, Counsel and Swiper actually replace

Emacs has several completion front ends, and the choice between them is mostly about how much of the minibuffer you are willing to give up. Ivy is the base layer: a generic completion mechanism that the README describes as operating similarly to schemes such as icomplete-mode, with the stated aim of being more efficient, smaller and simpler. That aim is the whole pitch. Ivy does not try to be a framework you build on top of; it tries to be the thing that appears when any command calls completing-read or completion-in-region.

Counsel is where the practical value sits. It provides versions of common Emacs commands customized to use Ivy well. The README gives counsel-find-file as an example: pressing DEL moves you to the parent directory, which is a small thing until you have spent a decade navigating with the default find-file prompt. Enabling counsel-mode remaps the built-ins wholesale, so execute-extended-command becomes counsel-M-x, describe-function becomes counsel-describe-function, find-file becomes counsel-find-file, and so on through a table of seventeen mappings.

Swiper is the search side. It is an alternative to Isearch that uses Ivy to show an overview of all matches, which is the difference between jumping to the next hit and seeing where every hit is. The README notes that a Helm version, swiper-helm, also exists. If you only want better search and nothing else, swiper is the piece to install; if you want the completion layer, you are installing ivy whether you meant to or not, because swiper depends on it.

How the completion layer is wired

The mechanism is deliberately indirect. Ivy does not take over the minibuffer by rebinding keys globally in the way a modal editing package might. Instead, ivy-mode arranges that any Emacs command invoking completing-read or completion-in-region routes through Ivy. That is the architectural decision that makes the package easy to adopt and hard to reason about at the same time: you do not have to change your commands, but you also cannot see from your own configuration which commands will change behavior once the mode is on.

The repository layout reflects the layering. ivy.el is the core, with ivy-faces.el for display and ivy-overlay.el for the overlay-based prompt. colir.el handles color translation between the completion buffer and the terminal or GUI frame, which is why the package can render candidates with faces without the completion buffer looking wrong. swiper.el and counsel.el sit on top. ivy-avy.el and ivy-hydra.el are optional integrations, and the Makefile treats them as such: they are listed in opt-elcs and compiled with an extra step that loads targets/elpa.el and activates the corresponding packages first. If avy or hydra is not installed, those two files are not part of the default build.

The test target is worth noting because it tells you how the authors expect the code to be exercised. It compiles the sources, then runs ivy-test.elc under ert-run-tests-batch-and-exit with Emacs started as emacs -Q -batch -L . That is a batch, no-user-init run: the tests cannot depend on your configuration, which is the right call for a package whose entire purpose is to change minibuffer behavior.

Installing Ivy, Counsel and Swiper from ELPA or apt

The README gives two supported routes. The first is the package system: install the ivy package from GNU ELPA or MELPA, and the same for counsel and swiper. Installing ivy from GNU ELPA or MELPA also installs the manual under the (ivy) Info node, so the documentation arrives with the code rather than as a separate download.

(require 'ivy)
(ivy-mode)

Calling ivy-mode enables generic Ivy completion, including specific completion for file and buffer names, according to the README. Nothing else is required for the base completion layer to work.

The second route is the distribution package. Users of Debian 10 or later, and derivatives such as Ubuntu 18.04 or later, can install all three at once, and there is a separate package for the Hydra integration.

sudo apt install elpa-counsel
sudo apt install elpa-ivy-hydra

A first real use is to wire the commands you actually type. The README's small config example sets ivy-use-virtual-buffers and enable-recursive-minibuffers, then rebinds keys: C-s to swiper-isearch, C-x C-f to counsel-find-file, M-x to counsel-M-x, and C-c C-r to ivy-resume. The example also notes that parts of it can be replaced by enabling counsel-mode, which remaps the built-ins for you. In practice you would pick one approach: enable counsel-mode and rebind only what the remapping table does not cover, or skip counsel-mode and rebind each command explicitly as the example does. Doing both is redundant.

If you build from a source checkout instead of a package archive, the Makefile provides the targets. The deps target installs dependencies by loading targets/elpa.el and calling ivy--elpa-install, and compile then byte-compiles the source list.

make deps
make compile
make test

The compile target produces colir.elc, ivy-faces.elc, ivy-overlay.elc, ivy.elc, swiper.elc and counsel.elc, plus ivy-avy.elc and ivy-hydra.elc when those optional packages are available.

Where the package model gets in the way

The most concrete limitation is versioning. The three most recent releases listed for the repository are 0.13.0 from 2019-10-16, 0.12.0 from 2019-07-20 and 0.11.0 from 2019-01-26. The last push to the default branch was on 2026-09-13, so development has continued for years after the last tagged release. Anyone pinning to a release number is pinning to something from 2019. In practice this pushes users toward MELPA, which builds from the repository state, or toward the GNU ELPA package, and away from any workflow that expects semantic version tags to track the code. That is a real cost for anyone who wants to reason about upgrades in terms of versions.

The second limitation is the coupling. Swiper is advertised as an Isearch alternative, but it uses Ivy to render the overview, so you cannot take Swiper alone. If your objection to Ivy is the way it takes over completing-read, installing Swiper does not avoid that; it imports it.

The third is the mode itself. Because ivy-mode intercepts completing-read and completion-in-region globally, the blast radius of enabling it is every command in your Emacs that uses either function, including commands from third-party packages you have not audited. The README does not document a per-command opt-out or a rollback procedure for a command that behaves badly under Ivy. If you maintain a large configuration with many packages, that is the thing to test before you commit, not after.

Finally, this is Emacs Lisp and nothing else. There is no standalone binary, no editor-agnostic server, no command-line tool. If you do not use Emacs, none of the three packages is available to you in any form.

Helm as the other completion front end

The natural comparison is Helm, and the repository itself points at it: the README states that a Helm version of Swiper is available as swiper-helm. That single line is the honest summary of the relationship. The two projects solve overlapping problems and there are ports in both directions.

The difference in approach is scope. Ivy presents itself as a generic completion mechanism that aims to be smaller and simpler, and the repository structure backs that up: one core file, a faces file, an overlay file, a color-translation file, and two optional integrations. Helm's model is a broader framework with its own sources, actions and display conventions, and the swiper-helm port exists precisely because someone wanted Swiper's search behavior inside that framework rather than the other way around. Choosing between them is less about which completes better and more about how much machinery you want in your configuration. If you want completion to be a thin layer that stays out of the way, Ivy's stated design goal matches that. If you want a single framework that also handles selection, actions and multi-source aggregation, the existence of swiper-helm tells you the Ivy side has nothing equivalent to offer, and you would be porting in the opposite direction.

Maintenance, releases and the licence question

The last push to the default branch was on 2026-09-13, which is recent, and the repository is not archived. Development is ongoing. That does not mean releases are frequent: as noted above, the most recent tagged release is 0.13.0 from 2019-10-16. The gap between the last release and the last push is the single most important fact for anyone planning an upgrade path, because it determines whether you consume the project through version numbers or through a rolling package archive.

Upgrade cost is low in one sense and non-zero in another. The packages are pure Emacs Lisp with no compiled native dependencies, so upgrading is a package-manager operation rather than a build pipeline. The non-zero part is behavioral: because ivy-mode changes how completing-read behaves for every command that calls it, an upgrade can change the feel of commands you did not touch. The Makefile's test target runs the ERT suite in batch mode, which is the mechanism available if you build from a checkout and want to verify a change before adopting it.

On licensing, the Makefile header carries the standard GNU General Public License notice, version 3 or later, and names the Free Software Foundation as copyright holder, with the comment that the file is part of GNU Emacs. The repository metadata does not list a licence identifier, so the Makefile header is the clearest signal available. The README does not discuss licence terms for the packages themselves. If you are redistributing or bundling these packages, read the licence text in the source files rather than relying on the metadata field, and treat the GPL notice in the Makefile as the starting point for that reading rather than as legal advice.

Editorial conclusion

Adopt it if you already live in Emacs and want completion, command dispatch and search to share one interaction model; skip it if you use another editor, since every entry point is an Emacs command. Before committing, check that your Emacs version satisfies the package dependencies and decide whether you want GNU ELPA releases or MELPA snapshots, because the repository's own release tags stop at 0.13.0 from 2019.

Frequently asked questions

Official sources

1. abo-abo/swiper on GitHub
2. Issues
3. Project website
4. README
5. Releases