Table of Contents



swiper-avy should use only the current window

Not all windows. See #117.

fix wrap-around for ivy-next-line

See #118.

swiper-avy should do nothing for empty input

See #50.

ivy-alt-done should require TRAMP if necessary

See #145.

swiper-query-replace shouldn't miss the first occurrence

See #144.

swiper should not deactivate mark

ivy-mode should not switch to TRAMP for certain input

See #145.

counsel-find-file should work better with TRAMP

"/ssh:foo" should not be cut off See #145.

counsel-find-file supports Windows drive letters

See #155.

counsel-file-file should work better with files that contain "~"

See #157.

counsel-M-x should respect ivy-format-function

See #150.

counsel-git-grep should position better on exit

See #153.

ivy-mode should re-scale text to minibuffer height

See #151.

counsel-unicode-char should use action-style call

See #160.

ivy-read should allow % in prompt string

See #171.

ivy-call should execute in proper window

See #176.

New Features


Open an Info file on the file system

When in Info-mode, press g and select either "(./)" or "(../)" to switch to file name completion. That file will be opened with Info.

Account for minibuffer-depth-indication-mode

If you have minibuffer-depth-indication-mode on, the minibuffer prompt will indicate the current depth. See #134.

Add fuzzy matching function

To enable fuzzy matching, set your ivy-re-builders-alist accordingly:

(setq ivy-re-builders-alist
      '((t . ivy--regex-fuzzy)))

See #136.

See also #142 for toggling fuzzy matching with C-o m.

case-fold-search optimization

Bind case-fold-search to t when the input is all lower-case:

  • input "the" matches both "the" and "The".
  • input "The" matches only "The".

See #166.

Allow to see the candidate index a la anzu via ivy-count-format

To have this feature, use something like this:

(setq ivy-count-format "(%d/%d) ")

See #167.

You can also set this to "", if you don't want any count, see #188.

Allow to add additional exit points for any command

Example for ivy-switch-to-buffer:

    (lambda (x)
      (kill-buffer x)
      (ivy--reset-state ivy-last))

After this:

  • use M-o k to kill a buffer
  • use M-o j to switch to a buffer in other window

You can always use M-o o to access the default action. When there is only one action, M-o does the same as C-m.

See #164.

counsel-describe-function and counsel-decribe-variable

Add a binding to look up the symbol in info

Press C-, to look up the symbol in info, instead of the default describe action. See #121.

Handle symbol-at-point better in non-Elisp buffers

See #126.


New face ivy-virtual

See #129.

Deal better with invisible buffers

See #135.

Add custom keymap

You can customize ivy-switch-buffer-map.

See #164.

Add extra actions

Add a kill-buffer action, and switch-to-buffer-other-window action.


Add Async

Make it fully async: the process git grep will be killed and restarted on new input. This results in almost no keyboard delay.

Own history variable


Own history variable

Having own history variable allows to get more use of M-p, M-n and C-r.


Switch to action-style call

This allows to make use of C-M-n and C-M-p.


Add Async
Add extra actions

In addition to the default action of opening a file add:

  • xdg-open action
  • dired action

Press M-o or C-o to access these actions.

Add own history


Add :matcher

A matcher is a function that accepts a regexp and a list of candidates and returns the filtered list of candidates.

The default matcher is basically cl-remove-if-not + string-match. If you'd like to customize this, pass your own matcher.

See counsel-git-grep-matcher for an example.

Allow to customize the initial input for all commands

Customize ivy-initial-inputs-alist for this. See #140.

ivy-sort-functions-alist should also examine this-command
:dynamic-collection is now a boolean

Pass the collection function as the second var instead.

New Commands


Execute the current action for the current candidate without exiting the minibuffer. Bound to C-M-m or M-RET or C-o g.


Forward to find-file with Ivy completion.

ivy-next-line-and-call as well as ivy-resume should work for this command.

The variable counsel-find-file-ignore-regexp allows to ignore certain files, like dot files. Input a leading dot to see all files.

The variable counsel-find-file-at-point allows to automatically use ffap. You also can do it manually with M-n when the point is on a file name.

The variable counsel-find-file-map allows to customize the minibuffer key bindings for this command.

Recommended binding:

(global-set-key (kbd "C-x C-f") 'counsel-find-file)

You can peek at files with C-M-n and C-M-p.

See #122 and #123.

See #152 about M-n, M-p and M-i switching directories when necessary.


Find a file on recentf-list.

Note that if your set ivy-use-virtual-buffers, recentf-list is merged into candidates list for ivy-switch-buffer. But if you want it separately, you can use this command.

See #124.


Add word at point to minibuffer input.

This is similar to what C-w does for isearch. However it's bound to M-j instead of C-w, since C-w is bound to kill-region - a useful command.

See #125.


Forward to execute-extended-command with Ivy completion. The candidate list will also display the key binding for each bound command.

This command will piggyback on smex for sorting, if smex is installed.

Use counsel-M-x-initial-input to customize the initial input for this command. By default, it's "^" - the regex character that indicates beginning of string. This results in much faster matching, since you usually type the command name from the start.

See #136 and #138.


Press C-o to toggle the Hydra for Ivy. It gives access to shorter bindings and many customizable options.

Use C-o > to grow the minibuffer. Use C-o < to shrink the minibuffer.

See #151.


Toggle executing the current action each time a new candidate is selected.

This command is bound to C-o c.

To explain how this is useful: C-M-m C-M-f C-M-f C-M-f is equivalent to C-o cjjj.


Inserts the current candidate into the minibuffer.

Press M-i if you want something close to the current candidate. You can follow up with an edit and select.

I find this very useful when creating new files with a similar name to the existing file: C-x C-f M-i + a bit of editing is very fast.

See #141.


Forward to load-theme with Ivy completion. Allows to rapidly try themes (e.g. with C-M-n).



Select an action for the current candidate and execute it. Bound to M-o.

Some commands that support M-o:

  • counsel-rhythmbox
  • counsel-describe-function
  • counsel-describe-variable
  • ivy-switch-buffer
  • counsel-locate


Forward to org-set-tags with Ivy completion.

Selecting any tag each time will toggle it on/off. The current list of selected tags will be displayed in the prompt.

See #177 and #91.


Forward to org-agenda-set-tags with Ivy completion. See #177.


Interactively ag using Ivy completion.


Use recoll with Ivy completion. See Using Recoll desktop search database with Emacs.

Install recoll with sudo apt-get install recoll.


Start swiper from the current isearch input.


Use this command to exit the minibuffer choosing not the current candidate, but the current text. Bound to C-M-j or C-u C-j.

See #183.



Fix :dynamic-collection not being sorted

When :initial-input contains a plus, escape it

See #195.

Set line-spacing to 0 in the minibuffer

See #198.

Enlarge the minibuffer window if the candidate list doesn't fit

See #198 and #161 and #220.

Fix minibuffer collapsing to one line

See #237, #229 and #77.

Use minibuffer-allow-text-properties

Allows ivy-read to return a propertized string.

Improve C-g out of a long-running async process

Use counsel-delete-process as :unwind.

Don't regexp-quote :preselect

See #245.

Fix ivy-partial for fuzzy completion

See #266.

ivy-resume should pass :caller

See #245.

Fix the regression in perfect match logic

See #270.

Fix pasting file paths on Windows

C-j should no stop completion for a pasted file path

C-M-j should use ivy--directory

When completing file names, expand the file name properly. See #275.

Use a specific blend method for dark themes

See #278.

Fix one-off bug in ivy-scroll-up-command and ivy-scroll-down-command

M-o shouldn't set the action permanently

So now it's possible to e.g. counsel-describe-function -> M-o d -> ivy-resume -> M-o o -> ivy-resume -> M-o i.

Fix swiper preselect issue with similar or identical lines

See #290.

Make ivy-completing-read handle history as cons

See #295.

Perform string-match in the original buffer

The syntax for whitespace, separators etc. is different for modes. See #298.

New Features


Make line numbers into display properties

Each candidate is now a single space plus the original string. The display property of the single space holds the line number. This means that it's no longer possible to match line numbers in queries, which is a good thing if you're searching for numbers.

Extend swiper-font-lock-ensure

Add mu4e-view-mode, mu4e-headers-mode, help-mode, elfeed-show-mode, emms-stream-mode, debbugs-gnu-mode, occur-mode, occur-edit-mode, bongo-mode, eww-mode, vc-dir-mode.

Add support for evil-jumper/backward

See #268.

Make compatible with visual-line-mode

swiper will split the lines when visual-line-mode is on. This is convenient for small buffers. For large buffers, it can be very slow, since visual-line-mode is slow. See #227.

Add swiper-toggle-face-matching

Bound to C-c C-f. At each start of swiper, the face at point will be stored. Use this command to toggle matching only the candidates with that face. See #288.

push-mark only if exited the minibuffer

C-M-n and C-M-p will no longer push mark and annoy with messages.

ivy-resume should restore the buffer for swiper

See #302.

Enable recursive swiper calls

While you swiper buffer-1, you can switch out of the minibuffer into buffer-2 and call swiper again. Exiting the second minibuffer will restore the first minibuffer.

To use this, you need to enable recursive minibuffers.

(setq enable-recursive-minibuffers t)

It's also useful to indicate the current depth:

(minibuffer-depth-indicate-mode 1)

See #309.

Fix for twittering-mode

The field text property is now removed before inserting text into the minibuffer. This fixes the swiper problems with twittering-mode. See #310.


Add manual

In the current state, the manual covers the most basic topics, like the minibuffer key bindings and the regexp builders.

Make <left> and <right> behave as in fundamental-mode
Truncate minibuffer prompts longer than window-width

See #240.

C-M-n should not leave the minibuffer

Make sure that the minibuffer window remains selected as long as the completion hasn't finished. For example, <f1> f to call counsel-describe-function, input "forward" and spam C-M-n to read the doc for each function that starts with "forward". The *Help* window popup would move the window focus, but this change moves it back to the minibuffer.

Add flx sorting

See #207. Since flx is costly, move the caching to an earlier point. This means immediate return for when the input hasn't changed, i.e. for C-n or C-p. When flx is installed, and (eq ivy--regex-function 'ivy--regex-fuzzy) for current function (through ivy-re-builders-alist), then sort the final candidates with ivy--flx-sort.

In the worst case, when some error pops up, return the same list. In the best case sort the cands that all match name by closeness to name.

How to use:

  1. Have flx installed - (require 'flx) should succeed.
  2. Configure ivy-re-builders-alist appropriately to use ivy--regex-fuzzy.

For example:

(setq ivy-re-builders-alist
      '((t . ivy--regex-fuzzy)))

Support hash tables

Since all-completions also works for hash tables, no reason not to support them.

Improve documentation of ivy-count-format

Now possible to set it with Customize.

Add ivy-index-functions-alist

Customize this to decide how the index, i.e. the currently selected candidate, is updated with new input. For example, one strategy is not reset it to 0 after each change.

Another strategy, used for swiper, is to try to select the first appropriate candidate after (inclusive) the first previously selected candidate. This way, if you're typing something that matches what is currently selected, the selection won't change.

See #253.

Add ivy-virtual-abbreviate

The mode of abbreviation for virtual buffer names.

Add ivy-case-fold-search

Used to override case-fold-search. See #259.

Add feedback for long-running async processes

Each time 0.5s pass after the last input, if the external process hasn't finished yet, update minibuffer with the amount of candidates collected so far. This is useful to see that long running commands like counsel-locate or counsel-ag (when in a very large directory) aren't stuck.

Promote ivy-extra-directories to defcustom
Promote ivy-sort-function-alist to defcustom
M-n should prefer url at point to symbol at point
C-x C-f M-n calls ffap-url-fetcher when at URL
Highlight modified file buffers with ivy-modified-buffer face

This new face is blank by default, but you can use e.g.:

 '(ivy-modified-buffer ((t (:background "#ff7777")))))

Work with enable-recursive-minibuffers

Store the old ivy-last in case ivy-read is called while inside the minibuffer. Restore it after ivy-call.

Allow user-specified matched candidate sorting

New defcustom ivy-sort-matches-functions-alist. See #269 #265 #213.

By default, Ivy doesn't sort the matched candidates, they remain in the same order as in the original collection. This option is the default, since it's fast and simple.

A small problem with this approach is that we usually want prefix matches to be displayed first. One solution to this is to input "^" to see only the prefix matches.

Now, another solution is to can set:

(setq ivy-sort-matches-functions-alist
      '((t . ivy--prefix-sort)))

Here's another example of using this defcustom:

     '(read-file-name-internal . ivy--sort-files-by-date))

After this, during file name completion, most recently changed files will be ahead.


Adds fancy highlighting to the minibuffer. See #212, #217, .


Bind t to toggle-truncate-lines

See #214.

Bind a to ivy-read-action


Make M-o r rename the buffer instead of switching.

See #233.


Allow customizing locate options

See counsel-locate-options. The current setting is:

(setq counsel-locate-options '("-i" "--regex"))

Support OSX

Use open instead of xdg-open. Modify counsel-locate-options for OSX, since there locate doesn't support --regex.

Use single quotes for the regex

See #194.

Add initial-input argument

See #289.


Now works in agenda

See #200.


Add own history


Add "definition" action

Use M-o d to jump to definition.

Show current-prefix-arg in the prompt

See #287.


Input '/sudo::' goes to current directory instead of root's home

See #283.

Fix directory validity check

See #283 #284.

Improve TRAMP support

Selecting items after // now works properly.


Use prefix arg to specify the shell command.

Remember to use M-i to insert the current candidate into the minibuffer.

See #244.

Allow counsel-git-grep -> ivy-occur -> wgrep

Using C-c C-o (ivy-occur) while in counsel-git-grep will produce a wgrep-compatible buffer.

ivy-occur gives full candidates

This means that the " | head -n 200" speed-up isn't used and full candidates are returned.


Allow to jump back with pop-tag-mark

Using C-. in:

  • counsel-describe-function
  • counsel-describe-variable
  • counsel-load-library

will change the current buffer. The buffer and point can be restored with M-* (pop-tag-mark).

I also recommend this binding:

(global-set-key (kbd "M-,") 'pop-tag-mark)

Resolve the name clash better

When the symbol is both bound and fbound, prefer the fbound one, unless the :caller is counsel-describe-variable.


Add initial-directory

Support alternative initial directory which helps other packages call this function with their unique starting directory.

Fix on Windows

Using the "–vimgrep" argument improves things.

New Commands


Bound to C-c C-o. Store the current completion session to its own buffer. You can have an unlimited amount of these buffers.


Bound to C-'.

Speeds up selecting a candidate that's currently visible in the minibuffer.


Bound to M-w.

When the region is active, call kill-ring-save. Otherwise, store all selected candidates to the kill ring.


Bound to C-M-o.

This is a non-exiting version of M-o (ivy-dispatching-done).


Bound to C-M-a. Select the current action. Don't call it yet.


Use swiper in multiple buffers. See #182.

Basic usage tips for selecting multiple buffers:

  • Use C-M-m (ivy-call) to add or remove one more buffer without exiting.
  • Use C-m (ivy-done) to add one last buffer.
  • Or use C-M-j (ivy-immediate-done) to finish without adding more buffers.
  • Hold C-M-n (ivy-next-line-and-call) to add a lot of buffers at once.


Open multiple cursors at all selected candidates.


New command to launch swiper for all open file buffers. Note that this can be excruciatingly slow if you don't clean up your buffer list often.


This is essentially swiper for huge files. It's not as smooth as swiper for small files, but has a faster startup and faster matching for files that measure in megabytes.


Bound to M-q. Perform query-replace on all matches in all buffers.


Complete Python symbols using Jedi.


Complete Common Lisp symbols using SLIME.


Give completion for inserting from the kill ring. See counsel-yank-pop-truncate defcustom and #218.


Package rename

Due to popular demand, swiper-0.7.0 is succeeded by ivy-0.8.0 in GNU ELPA. The contents of the package don't change, only the name. Make sure to remove the ~/.emacs.d/elpa/swiper-0.7.0 directory if you have it and M-x package-install ivy.


HTML documentation is available at

Texinfo documentation is in doc/ivy.texi.

The HTML file shouldn't be in this repository to avoid bloat, instead it's in the gh-pages branch at



Fix recursive minibuffer exit with C-g

Make it so e.g. C-h f C-h v C-g goes back to the describe-function selection.

Ensure the return result

In some cases, read-from-minibuffer will return the whole minibuffer contents (i.e. all available candidates). Return ivy--current instead.

Properly support matching ignoring order

See #296 and #329.

Insert intermediate candidates during async completions

See #340.

Initialize ivy-last to empty state

See #352.

Fix extra actions for completing-read

See #337.

Support a list of symbols as collection

See #375.

Define setq-local and defvar-local unless defined

With this commit, Ivy works on emacs-24.2. See #415.

Make M-o not modify the action

See #454.

Make sure user keybindings are respected

See #466.

Fix read-file-name with a specified dir

See #475.

Don't highlight the match in the file part

See #483.

Add a few tests for alists


Fix default-directory

This way, next-error etc will work properly.


Fix for small delta

See #339.

Check frame-root-window-p

See #380.


Use completing-read-default for tmm

See #316.


Recognize ! at the beginning of the str

See #318.

Prettify a bit

See #344.

Don't consider \\(?...\) a group

See #393.


Always return a valid window

Even if state is invalid.


Update cl-position logic

See #207.

Fix due to recursive update

See #323.


Don't null initial-input

This is specifically for 'read-file-name-internal collection. The input needs to be set to nil for e.g. rgrep, which supplies the absolute path as initial-input, resulting in a mess.

For now, don't set input to nil if :action was passed to ivy-read. See #336.

Don't deactivate region

See #377.


Use completion-all-completions

See #341.

Optimize for 1 candidate

When there's only one candidate, call the action immediately.

Add feedback for 1 candidate

When the sole completion is the same as the input, notify the user. See #350.

Bind completion-ignore-case

It's convenient to have it the same value as case-fold-search.


Give enough minibuffer space

See #402.

Allow to customize the action hint formatter

See #469.


Fix for nil value

See #349.


Don't fall back to switch-to-buffer

See #410.


No "\\_<" for dynamic-collection

"\\_<" regex is Emacs-specific and should only be done if :dynamic-collection is nil. It is nil for counsel-git-grep with repositories < 20000 lines, but non-nil for larger ones.

Fixes #409.


Pulse no longer

Repeated pulses within a short time span resulted in horrible window flickering.


Add a guard against null :action


Make C-g cancel gracefully

See abo-abo/avy#140.


Allow to exit with no candidates.


Improve for multiple occurrences on one line

See #314.

Fix "backward" search

When none of the previous candidates after the point match the current input, instead of returning 0, return the index of the last matching candidate. This is a good choice, because that candidate is the closest to the point of the initial search start.

See #319.

Return point

See #370.

Update regexp-search-ring

See #89.

Always remove '(field) text property

Allows to search better in modes for shell interaction.


Add modes

Add bongo-library-mode, bongo-playlist-mode, sauron-mode.

See #19.

Don't fail when font-lock is off

See #400.


Add check for make-string

See #481.


Fix issue with ivy--regex-ignore-order

See #342.

Re-display when no cands
Recognize error codes other than 1

See #394.


Fix window selection.

Use with-ivy-window, so that each new file chosen with e.g. C-M-n is selected in the same window.


Add :unwind

See #403.

compilation warnings

See #324.

New Features


Use flx for highlighting fuzzy matches

See #207.

Simplify the signature for :dynamic-collection functions

When given :dynamic-collection, assume the collection function only needs one argument - the string input.

Modify M-n prediction when region is active

When the region is active and M-n is called, insert the region contents into the minibuffer and deactivate the region. The region deactivation is done for swiper, to make it easier to search for multiple words or a subword.

Allow to compose collections
  • Example 1: async collection

    Stack recentf on top of counsel-locate:

    (defun small-test ()
      (cl-subseq recentf-list 0 10))

    Here, (original-source) represents the async candidates of counsel-locate. All extra sources are static - each function is called once to generate a list of strings, which will be filtered later.

    The order matters, so you can have e.g.:


    See #373.

  • Example 2: sync collection
    (defun my-extra-source ()
       (when (eq 'Git (vc-backend (buffer-file-name)))
         (list "git1" "git2" "git3"))
       (when (file-exists-p "doc/")
         (list (propertize "doc/" 'face '(:background "red"))))))
    (defun my-find-file ()
      (ivy-read "Find file: " 'read-file-name-internal
                :action (lambda (x)
                            (find-file (expand-file-name x ivy--directory))))
                :require-match 'confirm-after-completion
                :history 'file-name-history
                :caller 'my-find-file))

    The function my-find-file knows nothing about the extra source, it's only purpose is to introduce a :caller to attach things to, as to not to mess up e.g. counsel-find-file.

    The function my-extra-source gets called once in ivy-read via ivy--reset-state. It takes no args and returns a list of strings, possibly empty.

Improve documentation UI

Bind C-h m to ivy-help.

ivy-help-file is a new defvar pointing to the file.

Bind D in hydra-ivy to go to hydra's definition.

See #376 and #379.

Add ignore pattern toggling

C-c C-a is bound to ivy-toggle-ignore - a new command to toggle ignore patterns (user-configured filtering). If the ignore patterns are enabled and there are zero candidates after ignoring, display the ones that match the current text. This feature currently works for ivy-switch-buffer and counsel-find-file.

See #369.


Set completion-in-region-function

See #331.

Improve M-n for 'read-file-name-internal


Allows to customize ivy-occur per-command.

Add custom occur for ivy-switch-buffer

See #438 and #440.


New commands on j, k, c

(ivy-occur-toggle-calling): New command bound to c. (ivy-occur-next-line): New command bound to j. (ivy-occur-previous-line): New command bound to k.

This makes ivy-occur much more convenient, instead of gjgjgjg, just cjjj. Especially good for commands that change the contents of the other window, like describe-function or counsel-git-grep.


  • C-h f (describe-funtion)
  • run (self-insert-command)
  • C-c C-o (ivy-occur); C-o u also works.
  • cjjjjkkkk

New command ivy-occur-revert-buffer on g

Does what e.g. revert-buffer does for Help buffers.

Has special handling for counsel-git-grep, counsel-ag and counsel-grep: will run the shell command once more and reflect the updates in files.

Move ivy-occur-press from g to f.

Improve the feedback for j and k

The overlays will be more responsive now.


Allow this-command to be a key


(defun asdf ()
  (completing-read "prompt: " '("abc" "abcd" "def")))

(global-set-key (kbd "C-c t") 'asdf)

(setq ivy-re-builders-alist
        (asdf . ivy--regex-fuzzy)
        (t . ivy--regex-plus)))

This is useful for commands that you didn't write. For new commands that you write, consider using ivy-read and :caller.

See #330.


Call with t to affect all commands


 '(("i" insert "insert")))

Now an "insert" action will be available for all ivy-read sessions when pressing M-o.

See #337.


New defcustom group. See #389.


New variable. Configure when flx is used. See #207.


New variable. See #363.


New defcustom. See #367.


New defcustom.

When non nil, fix the height of the minibuffer during ivy completion at ivy-height. This effectively sets the minimum height at this level and tries to ensure that it does not change depending on the number of candidates.

See #353.


New API function.

Now used by switch-to-buffer and read-file-name.

See #399.


New defcustom similar to ido-ignore-buffers.

See #382 and #366.


New defcustom.

See #451.


Add virtual views

ivy-views variable stores pre-defined views. Allows to set a window configuration with many buffers from ivy-switch-buffer.

How to use: just set ivy-views appropriately. An example value is provided (but nulled, so that it's empty initially).


New defcustom

See #477.


Improve swiper-query-replace

To replace a symbol with a similar symbol,

  1. Press C-s M-n for swiper and select the symbol at point as input.
  2. Press M-q for swiper-query-replace
  3. Press M-n to yank the symbol to replace.
  4. Edit the replacement and RET.

Here step-3 was modified to yank e.g. "symbol" instead of "\_<symbol\_>" previously.


New variable for major modes that misbehave with font-lock-ensure. See #346.


New auto-updates position

See #401.


A minor-mode that remaps built-in functions that have counsel replacements available.

See #414.

Allow use of describe-prefix-bindings

See #441.


Add initial-input

See #336.

Change tramp prompt from "Find File: " to "[email protected]: "
Bind counsel-up-directory to C-DEL

New function that moves up to the parent directory and at the same time preselects the current directory. This is useful for moving up and down a file tree quickly.

See #343.

Customize M-n action

This feature allows to quickly visit Github issues from either magit-commit-mode or from a version-controlled file. The point has to be at the "#" char in e.g. "#123", that represents an issue.

It's possible to customize ivy-ffap-url-functions to do a similar thing for places other than Github.

The C-x C-f M-n key binding will work better with counsel-find-file, for plain find-file it will open a dired buffer in addition to opening the URL.

Can un-ignore dotfiles with a leading dot input

When ivy-text starts with a dot, don't use counsel-find-file-ignore-regexp. The generic way to do this is with C-c C-a (ivy-toggle-ignore), but this is faster and more convenient.

See #408.

Bind M-o f to find-file-other-window
Correctly expand file name at point

See #430.

Add display transformer

See #458.

Add magic slash that changes the directory

Update to the behavior: the slash ("/") will enter a directory even if its name isn't completely typed out if either:

  1. It's the only candidate.
  2. The candidate index isn't 0, i.e. "C-n" has been typed at least once.
  3. The input isn't "/".

The above rules still allow to keep the old behavior with "//" moving to root and "/ssh:" opening tramp.

This is an experimental feature, please report if it breaks someone's workflow.

See #321 and #480.


Bind C-c C-m to counsel-git-grep-switch-cmd

The initial command always runs on all files.

To run only on *.el files, C-c C-m followed by M-i -- *.el. To run on *.c and *.h files, C-c C-m followed by M-i -- *.c *.h. To switch to all files again, C-c C-m and select the appropriate entry.

See #420.



New defcustom that replaces counsel-locate-options.

See #385.


New function. See #390.


New function. See #426.


Truncate during display

During the completion, only the context around the match will be shown. By default, the context is +2 lines above and +2 lines below the match. It can be adjusted with counsel-yank-pop-truncate-radius. Additionally, ivy-height is temporarily bound to 5 during completion. This way, the maximum minibuffer height should be 1+4*5=21 lines.

See #315.


Display hex codes in left column.


Preselect the current song



Allows the command run by counsel-ag-function to be customized. There are several reasons to allow this: The vimgrep option is a recent addition; on windows it's more convenient to use pt; and the user might want to customize ignored files.

Standard value:

(setq counsel-ag-base-command "ag --nocolor --nogroup %s -- .")

See #335.

Add dir prompt for C-u

See #429.

Add counsel-ag-map

See #462.


New defcustom.


Add optional exit-code table

This argument can be used to associate exit codes with the underlying reason. Used in counsel-ag-function to signal that an exit code of 1 means that no matches were found.

See #421.


New defcustom

See #424 and #425.


Reveal outlines

Just like swiper.

Should pick candidates closest to point

Fixes the algorithm selecting the first matching candidate in case there are 0 matching candidates following point. Now the last matching candidate will be selected, resulting in less scrolling.

Speed up x40 times

The default shell command will not use --ignore-case switch for grep. It's a bit less convenient, but results in a huge speed-up.


Add help action

Bound to M-o h by default.

See #452.

New Commands


Completion for the menu bar items. For example:

counsel-tmm -> Options -> Set Default Font....

Thanks to completion, the latter stages of the chain would look like: op RET set RET.


Jump to a buffer position indexed by imenu.


Show a list of all defined keys, and their definitions. Describe the selected candidate. See #332.


Offer completion for process-list

The default action deletes the selected process. An extra action allows to switch to the process buffer.

See #357 and #398.


Remap switch-to-buffer-other-window to ivy-switch-buffer-other-window for ivy-mode.

See #361.


Search through all available git stashes.

See #374.


Call the git log --grep shell command and search through the output.


Grep for a string in the current directory using pt.

See #434.


Launch a Linux desktop application, similar to Alt-<F2>.

See #446.


Browse Eshell history.

See #459.


Browse shell history.


New command: automatically use swiper for smaller buffers and counsel-grep for larger buffers.

Adjust with:

(setq counsel-grep-swiper-limit 300000)

By default, the splitting predicate is 300K bytes in a file.




Fix color parsing in terminal. See #541 and #543.


Check for an additional 141 return code.


Use sync on remote

See #669.

Add missing parameter

See #858, #861.


Improve stability on arcane systems

It can happen that (all-completions "" 'read-file-name-internal) may fail on systems with symlinks. I think it's related to the file functions trying to compute occupied space. In any case, a plain directory-files is roughly the equivalent and is less likely to fail.

Check compat between preselect and initial-input

See #514, #515.

Prevent expand-file-name nil

See #518.

Don't crash if default-directory is nil

See #586.

Allow to C-y a "/ssh:" file
Press M-n on issue works for newer magit version

See #692.

Fix when initial input is a file name

See #744.

Account for file-name-directory returning nil

See #780.

Fix RET on no input

See #782.

Fix RET when file exists

See #792.


Add a better error message.

See #537.

Add x action

To open externally.


Quote :preselect.


Don't grep on compressed files. See #536.


Improve readability

See #558.

Force rescan if requested

See #631.


Fix doc, see #721. Add preselect, see #722.


Don't quit on bad data

See #604.

Check if dir exists

See #896.


Add noconfirm flag in counsel-load-theme-action.


Make counsel-locate-action-extern interactive

See #605.

Add w32 support to counsel-locate-action-extern

See #607, #688.


Fix interaction with repeat

See #564.

Preserve last-command

See #891, #893.


Perform in the minibuffer. See #890.


Add shell-quote-argument. See #713.


No longer depends on helm-rhythmbox.


Fix candidates not showing sometimes.


Fixed typos in the doc

See #497, #809.

Added ivy-format-function to the doc

See #577.

Added info on generating the doc

See #601.

Added info on associating values

See #714.

Update package names on ELPA/MELPA

See #833.


Recompute index after filter.

See #491.


Improve. See #843.


Fix for ivy-display-style nil. See #828.


Fix max-mini-window-height. See #732.


Scroll to first command. See #829.


Ensure it returns legal regexps. See #765.


Simplify. See #827.


Don't modify recentfs or bookmarks. See #821.


Set default-directory, see #717, #760, #779, #810. Recursive logic, see #924, #937.


Fix double insert bug. Fix common length bug. See #528. Remove :require-match, see #907.


Remove string properties, see #517. Remove with-ivy-window, see #928.


Add correction. See #737.


Define with defconst, see #938.

ivy-hydra is now a separate package on MELPA

See #464, #512.


Update docstring, see #525.


Move ivy-toggle-regexp-quote from M-q to M-r.

See #566.

Remap scroll-up/down-command

Instead of assigning C-v / M-v so page up/down works. See #797, #798.

Remap backward-delete-char-untabify to ivy-backward-delete-char
Rebind C-v and M-v

The ultimate solution to have PgUp and PgDown and whatever else was mapped to scroll-up-command bound in ivy-minibuffer-map. While still having the standard C-v and M-v bindings.

See #797, #798, #535.


Pass the whole cons cell to action, see #634.


Fix for :dynamic-collection. See #946.


Document all args

See #533.

Use predicate when reading file names

See #804.


Use a lighter color for dark themes, see #646.


The original default-directory will be restored, see #591.


Improve. See #870.


Reset index to 0 on input

See #522, #513.


Obey ivy-ignore-buffers. See #745.

Recursive minibuffers with two emacsclients

See #738.

shrink minibuffer after reading actions

See #764, #402.


Fix "foo!bar" syntax

See #565.

Now respects ivy-re-builders-alist

See #613.


(setq ivy-re-builders-alist
	  '((swiper . ivy--regex-fuzzy)
	    (t . ivy--regex-plus)))


Require avy, see #593.


Add forth-mode, see #526. Add forth-block-mode, see #527. Add bookmark-bmenu-mode. Add nix-mode, see #879. Add circe-mode, see #900, #901.


Fix regression, See #673. Don't use virtual buffers, See #705.

New Features


Extend more

See #576.

Prompt for extra args when using prefix arg

See #774.

Support limiting in files

See #820, #822, #823.


New hook for counsel-ag/grep/pt. See #800, #751.



When non-nil and a directory is selected from counsel-bookmark, forward the choice to counsel-find-file instead of opening a dired buffer. See #813.


Add binding to jump to a bookmarked directory without quit

Press M-o b to set the current directory to one of the virtual buffers' directories. You continue to select a file from that directory.

See #531.

Add counsel-find-file-root

Press M-o r to find the current file as root. See #948.


Add counsel-git-cmd

See #590.


Support custom per-project commands

The idea is to grep several Git repositories at once. For example, my Emacs config is a Git repository with many Git submodule repositories inside.

When used with C-u, and inside counsel-git-grep-projects-alist, use the corresponding command instead. Additionally, counsel-git-grep-proj-function is used.

For a possible implementation of the custom git-grep command, see:

See #616.

Reveal text hidden in outlines
Works with "Git for Windows" and native Emacs build
Fix for files with spaces in the name

See #700.

Fix g (counsel-git-grep-occur)

Things go wrong when `ivy-text' is changed from the original value. Extract ivy-text from the buffer name.

Quote the directory name. See #811.

Update quoting

See #876.


The initial value for counsel-git-grep-cmd.


Add counsel-git-log-cmd

Allows to customize the command, see #652.



Customize the search path.


Allow to find library with an action

See #873.


Bind counsel-info-lookup-symbol

Substitutes info-lookup-symbol, see #493.

Bind C-r for eval-expression and shell-command

Press C-r while inside the minibuffer during eval-expression or shell-command to get completion for history.


Add initial-input arg. See #757.


Add leading zeros to the display

See #662.

Support universal argument

See #868.


Add counsel-yank-pop-separator

Allows to customize the separator. See #660.


completion at point
New defcustom, which decides how to display the candidates.

ivy-completion-in-region will use completion at point by default.

Related: #707, #712, #788.


Set this to have ivy-next-action and ivy-prev-action wrap around.


This is a convenience extension to the existing ivy-set-actions. See #470.

ivy-case-fold-search additional value 'always

If the value of ivy-case-fold-search is set to 'always, the search is always case-insensive, regardless of the input. See #916.


Add support for multiple-cursors, see #547.


Customize the highlighters. See #691, #654, #827.


New defcustom. Decide if ~ or ~/ should cd home.

See #687, #679.


Allow to set the prompt using the :caller as key.


An advanced override of the prompt string.


Extends the options for sorting file names. See #498.


Set :caller to this-command

Improves sorting customization. See #899.

Don't :require-match for null

See #909.


New defcustom. See #892.


Alternative action list M-o using Hydra

Not hiding the candidates and using a single line for actions results in a more distraction-free experience.

Use this code to turn it on:

(require 'ivy-hydra)


RET now switches to candidate window
read-only-mode is enabled

See #720.

Set view-read-only locally

See #789.

Run wgrep-setup

See #904.


Make key binding for other window action consistent

By default, M-o j will select the file or buffer in other window, for both ivy-switch-buffer and counsel-find-file.

Facilitate sorting of cons cells

See #554.

(defvar ivy-sorter-data '(("b 1" . 1) ("a 2" . 2) ("d 0" . 0) ("c 5" . 5)))

(defun isn (a b)
  (< (cdr a) (cdr b)))

(add-to-list 'ivy-sort-functions-alist '(ivy-sorter . isn))

(ivy-read "string: " ivy-sorter-data
          :sort t
          :caller 'ivy-sorter)
Add prefix arg for action functions

See #552.

Single actions:

C-m ivy-done store prefix
M-o ivy-dispatching-done store prefix
C-j ivy-alt-done store prefix
C-M-j ivy-immediate-done store prefix
TAB TAB ivy-partial-or-done unsupported
C-' ivy-avy unsupported

Multiple actions:

C-M-m ivy-call store prefix, type prefix again for next call
C-M-o ivy-dispatching-call store prefix, type prefix again for next call
C-M-n ivy-next-line-and-call store prefix, type prefix again for next call
C-M-p ivy-previous-line-and-call store prefix, type prefix again for next call

An example application:

no prefix prints first number in a message-box one prefix prints last number in a message-box numeric prefix selects the index to print in a message-box

(ivy-read "choose: " '(("a" 1 2 3)
                       ("b" 3 4 5))
          (lambda (x)
            (message-box "%s"
                           ((null ivy-current-prefix-arg)
                            (elt x 0))
                           ((equal '(4) ivy-current-prefix-arg)
                            (car (last x)))
                            (elt x (prefix-numeric-value ivy-current-prefix-arg)))))))
Breaking change for alist type collection actions

The action will be called with collection's ITEM, instead of (cdr ITEM) like before. This allows to simplify the logic of complex action functions: they don't have to look up the full item by string in their own collection, moreover they don't have to know anything about their collection.

Implement unique index for alist completion

The uniqueness assumption is that the completion system is passed a list of unique strings, of which one (or more) are selected.

Unlike plain string completion, alists may require violating the uniqueness assumption: there may be two elements with the same car but different cdr. Example: C function declaration and definition for tag completion.

Until now, whenever two equal strings were sent to ivy-read, only the first one could be selected. Now, each alist car gets an integer index assigned to it as a text property 'idx. So it's possible to differentiate two alist items with the same key.

Make with-ivy-window not necessary in the action function

This allows for a lot of simplification, e.g. use insert instead of (lambda (x) (with-ivy-window (insert x))).

See #639.


Add ivy-sort-function-buffer

Puts e.g. the *scratch* buffer ahead of the misc buffer if the input is "sc", since it's almost like a prefix match.

See #595.

Sort virtual buffers after open buffers

See #706, #743.


Allow to customize faces in ivy-switch-buffer by the mode of each buffer.


(setq ivy-switch-buffer-faces-alist
      '((emacs-lisp-mode . swiper-match-face-1)
        (dired-mode . ivy-subdir)
        (org-mode . org-level-4)))


Add option for swiper line number to be searchable

See swiper-include-line-number-in-search and #562.

Restore window position after using swiper.

Relevant for high settings of scroll-conservatively. See #643.

Improve fuzzy highlight

If you've set the regex builder to fuzzy (non-default), you'll get a highlight quality on par with the default one. See #651, #653.

Add char-fold-to-regexp

See #622.

Add compatibility with evil-ex-search

See #887.

Apply evil search highlighting

See #888.

Set evil-ex-search-direction

See #947.


New defcustom. When non-nil, swiper default action will go to the beginning of the match instead of on its end. This behavior is inspired by vim's and evil's way of searching.

See #944, #942.

swiper-avy works with more regexp builders

See #932.


Is now async

This means extremely fast startup time.

Additionally, the feedback to input is quite fast even with a hundred buffers. This is because, unlike swiper, line numbers are not computed. Computing line numbers, while situationally useful, is really slow for huge buffers, and even slower for dozens of huge buffers.

See #620.

Press M-q for query-replace

See #623.

Ignore TAGS buffers

See #787.

Consider magit stash buffers

See #819.

Fix case-fold-search

See #880.

New Commands


Completion for bookmark-jump.

Can delete and rename bookmarks, see #758.


See #815, #921.


See #815.


See #826.


Picks up company's candidates and inserts the result into the buffer. See #331, #547.


See #585, #703.


Like, counsel-file-jump, but for directories.


Completion for dpkg -l.


See #815.


Jump to a file from a list of all files in the current directory, see #609, #610.


A helpful and unsurprising alternative to using C-. with counsel-load-library. See #794, #801.


Call a head of the current/last hydra by name. See #696.


Inline C++ completion using Irony.


See #834.


See #825.


Completion for outlines in the current buffer.


Manage packages. Allows installing, deleting, describing etc. See #869, #872.


Renamed from ivy-recentf, see #624.

Added actions in #701:

  • j for find-file-other-window
  • x for counsel-find-file-extern

Remove text properties, see #770.


Grep for a string in the current directory using rg. Use counsel-rg-base-command to customize. See #784, #785, #795, #796.


Call the rpm shell command. See #695.


Completion for semantic tags.


Completion for setting a variable to a value. See #544, #546, #549, #550, #556.


Search through history in shell-mode. See #689.

When counsel-mode is on, M-! C-r will call counsel-shell-command-history.


And ivy-pop-view.

  1. Use ivy-push-view to store a view - your current window tree. This contains: all windows on the current frame, and their configuration w.r.t. horizontal or vertical splits. The point positions in each window are stored as well.
  2. Use ivy-switch-buffer to select stored views.
  3. Use ivy-pop-view to delete a stored view that you don't want any more.

See #584.


Modify ivy-sort-functions-alist to allow a list of sorting functions to apply to a collection. The car of this list is the current one. ivy-rotate-sort then rotates this list through the different possibilities. Bound to C-c C-s. Here is a simple example to illustrate.

(setq ivy-sort-functions-alist
      '((read-file-name-internal .
                                (ivy-sort-file-function-default string-lessp string-greaterp))
       (internal-complete-buffer . nil)
       (counsel-git-grep-function . nil)
       (Man-goto-section . nil)
       (org-refile . nil)
       (t . string-lessp)))

M-x find-file RET C-c C-s now switches from the default sorting to using string-lessp. C-c C-s again switches to string-greaterp and so on.

See #845, #927.




Fix default ag command on Windows, see #1221.


Don't break when search string begins with "-", see #1048.

Fix quoting, see #1240.


Various fixes, see #969.


Fix regex, see #1089.


Obey find-program, see #1181.


Fix C-y when pasting a file path.

Fix magic slash regression, see #1027.

Don't quote regex for initial-input.

Don't bind find-file-hook if not necessary, see #627, #1118.

Fix completion of relative directories, see #1055.

Make sure foo/ directory goes before foo-bar/ directory, see #1315.


Use xargs -d '\n', see #1323.


Fix error on 24.5, see #1107. Fix for Windows, see #1176.


Fix output with negative pattern, see #1173.

Fix bug, see #1225.


Fix warning, see #1097.


Optimize text props, see #1264.


Ignore blank candidates, see #1122.


Fix regex, see #1299.


Add "–", see #1266.


Add trailing space to prompt, see #1245.


Various fixes, see #1018.


Handle cygwin, see #1314.


Don't rebuild cache on every call, see #1085. Add own history, see #1185.


Fix package removal, see #970.


Handle defcustom with multiple entries, see #960.


Work around ring-elements, see #1148.


Handle cons arg, see #1322.


Various fixes, see #997, #1327, #1334, #1336.

Don't add :preselect to collection, see #1017.

Avoid setting ivy window as minibuffer, see #1051, #1053.

Init index with 0, see #1080.

ivy-initial-inputs-alist should use :caller first, see #1068.

ivy--sorted-files should always use predicate, see #1121.

Simplify re-builder / highlight, see #1147.

Ensure bookmarks are loaded, see #1160.

Fix arrows not working for ivy--regex-ignore-order, see #1159.

Fix C-M-j for ivy-completion-in-region-action, see #1178.

Correct spelling, see #1179.

Ensure action and display transformer are called from initial buffer. See #1182.

Allow "!" and space to be escaped in ivy--regex-ignore-order. See #976.

Call ivy-overlay-cleanup only when needed, see #1211.

Don't require prompt to end in ": ", see #1207.

Remove empty string from collection, see #1230, #1236.

Fix "/sudo::" in current dir, see #1232.

Fix prefix issue, see #1244.

Update prompt even if there are no candidates. See #1183.

Also check this-command for sorting, see #1294.


Delete action duplicates by key, see #1296.


Fix logic when scrolled, see #1004.

Exit silently, see #1073.

Select correct candidate when using display transformer, see #1255.


Add some entries, and tests. See #1049.


Fix length bug, see #1251.

Fix sole match case, see #1252.


Fall back when there's no space, see #1136. Fall back when there's no vertical space, see #1136. Check for point-min, see #1267. Fix for org-indent-mode.


Check if git is present, see #1216.


Fixup, see #1004.


Fix entry for man, see #1226.


Fix double pop-to-buffer issue, see #1284.

Don't fail if buffer was killed.

Fix regex passed to grep, see #1299.

Use setq-local, see #1318.

Add ivy--dirname-p, see #1317.


Fix interaction with case-folding, see #1019, #1021. Fix downcase for non-string, see #1024, #1036.


Should not insert the last history item unless the currently-selected completion candidate is the first in the list, otherwise it's impossible to navigate back up with successive applications of this command, see #1137.


Extend docstring, see #1308.


Use with-output-to-string, see #1300.


Protect against match-beginning / match-end not integerp. See #1188, #1192.


Turn off reveal-mode for the duration, see #1312.


Various mode additions.


Add treemacs-mode, see #1212.

Add magit-popup-mode, see #1274.

Add adoc-mode, see #1275.

Add bbdb-mode, see #1276.

New Features


When an external program output is used, first check if the program is installed, see #1076.

Allow async commands on Tramp buffers, see #1229, #1233.


Configure async delay. See #1149.


New defcustom. See #1122.


Highlight interactive functions, see #981, #982.


Customize counsel-describe-function. Useful for See #1321.


Customize which symbol will be initial for counsel-describe-function, see #1088, #1330.


Highlight custom variables, see #980, #982.


Offer completion-ignored-extensions, see #1092.


Allow to customize fzf work directory.


Add optional initial-input, see #1074.


New defcustom, see #524, #1042.


New defcustom. See #1122.


Don't attempt to save readonly files, see #999.

Prevent opening an already opened file, see #1001.

Improve logic, see #1290.

More uniform interface, see #1313.


Allows to use C-l to recenter. See #1180.


Various improvements, see #897, #959.

Press M-o d to open the desktop file, see #897.


Sort by location, see #1006.

Fixes, see #1328, #1329.


Add counsel-faces, see #1259.


Limit results to 150 columns, see #988.

Never use color results, see #1060.

Search whole Git repository, not the current directory.


Show candidates in order, see #1003.

Adapt to ucs-names being a hash table in emacs-26, see #1223.

Make lazy, see #1204.


If the current directory is remote and it's not possible to go up any further, make the remote prefix editable. See #1242, #1227.


Added to ivy-ffap-url-functions by default.

Customize counsel-url-expansions to be able to browse various links with C-x C-f M-n. See #1164.


Don't restrict to 3 chars or more, see #973.

Press M-o d to remove an item from the kill ring.

Ignore empty candidates, see #1043.


Add i and w as global actions

In any completion session:

  • Press M-o w to copy the current candidate to the kill ring.
  • Press M-o i to insert the current candidate into the buffer.
Bind <next> and <prior>

See #1260, #1332.


Off by default. When on, and there's only one candidate, use it automatically without a completion session.


Preselect last dir, see #1257.


Use :initial-input and :unwind. Previously, Ivy's "prefixing" and "perfect match" index logic was messed up for completion-in-region. The reason being is that the initial prefix was never passed to Ivy: instead, the collection was pre-filtered on the prefix and a "new" completion session didn't know about it.


Quit with C-g, see #922.

Break hint into columns, see #953.


Customize what / does when completing file names, see #998, #1009.


When completing file names, counsel-cmd-to-dired is called, resulting in a Dired buffer.


Bind R to read-only-mode, see #1273.


Add new argument def, see #1047, #1049, #1052, #1112.


Allow to quit with ESC for better work with evil, see #952.


Bound to C-o m. Customize with ivy--preferred-re-builders. See #1093, #1094.


Compose faces better, see #992.

M-o f will call counsel-find-file from current directory, see #1298, #1295.


New defcustom. See #1110.


When non-nil, make the prompt line selectable like a candidate.

Calling ivy-done or ivy-alt-done on a selected prompt forwards to ivy-immediate-done, thus exiting with the current user input instead of the selected candidate.

See #1059, #1063, #1090.


Disable read-only for the duration, see #1273.

New Commands


Like counsel-ag, but with ack. See #1075.


Completion for apropos, see #1014.


Completion for file registers, see #1057, #1066.


Completion for fzf. See #1151, #1263.


Completion for git-worktree. See #989, #1114, #1115.


Completion for git-checkout. See #1187.


Supersedes counsel-expression-history and counsel-shell-command-history. See #1237.


Completion for org-capture. See #1320.


Browse all attachments for the current Org file.


Completion for Org headings. See #1005, #1008, #1011, #1012, #1013.


Completion for Org headings in all open buffers. See #1005.


Switch to a shell buffer, or create one. See #990.


Bound to C-d in ivy-occur-mode. Allows a sort of a todo-list workflow.


Switch to one of the window views stored by ivy-push-view. You can use it separately from ivy-switch-buffer now. See #929, #1109.