# vim-grepper: asynchronous searches that feed the quickfix list from any grep tool

> vim-grepper is a Vim and Neovim plugin that runs a search with whichever grep tool you prefer, ag, ack, git grep, ripgrep, pt, sift, findstr, or plain grep, in the background, and collects the matches into a quickfix or location list. The author considers it feature-complete and is not adding new features.

**mhinz/vim-grepper** — :space_invader: Helps you win at grep.

- Repository: https://github.com/mhinz/vim-grepper
- Stars: 1,247 · Forks: 62
- Language: Vim Script
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/mhinz-vim-grepper

## Any grep tool, one entry point

vim-grepper lets you use your favourite grep tool to start an asynchronous search, and all matches will be put in a quickfix or location list. The supported tools are listed with links in the project summary: ag, which is The Silver Searcher, ack, git grep, ripgrep, pt, which is The Platinum Searcher, sift, findstr for Windows, and grep itself.

That list is the plugin's central idea. The tools are not interchangeable in practice. ack has its own matching language. The Silver Searcher and the Platinum Searcher are tuned for speed on source trees. findstr is the one that ships with Windows. Each of them has different defaults, and each of them has an opinion about which files to look at.

So the plugin's job is not to search. It is to run the search you would have run, in the background, and to put the results somewhere you can navigate. That is a small job, and it is one that each individual tool's own Vim plugin would otherwise have to do separately, which is why the project points out that if you like ack.vim and ag.vim you will love vim-grepper.

The asynchronous part is what makes it feel different from running the tool in a shell and opening the result. A search that takes a second or two does not block your editor, and the results land in a list you can step through with the usual quickfix motions.

The repository is Vim Script, with a `plugin/` directory holding the plugin code, a `doc/` directory for the help file, a `test/` directory, a `CHANGELOG.md`, and a `CONTRIBUTING.md`. The default branch is `master` and the last push was on 2026-07-20.

## Three ways to start a search, and which one you reach for

The project summary describes three interaction modes, and they differ in how much you have to spell out.

The prompt uses `:Grepper` to open a prompt, enter your query, optionally cycle through the list of tools, and fire up the search. Cycling through the tools from the prompt is the distinctive part, because it means the tool choice is a runtime decision rather than a command choice, so you can try the same query against ripgrep and then against the Silver Searcher without rewriting the command.

The operator uses the current visual selection to pre-fill the prompt or to start searching right away. So you select some text, press the operator mapping, and either the prompt appears with your selection already in it, or the search starts on it. The pre-fill variant is the useful one for a repeated search, and the immediate variant for a one-off.

The commands give the widest range of flags, which the project says makes it extremely flexible. And every supported tool comes with its own command for convenience, so `:GrepperGit`, `:GrepperAg`, and so on. They are all built atop `:Grepper`, which is the important structural fact: the per-tool commands are not separate implementations, they are the same implementation with the tool preselected.

The plugin is installed with your favourite plugin manager, and the example given is vim-plug:

```
Plug 'mhinz/vim-grepper'
```

If you prefer lazy loading, the mapping form is:

```
Plug 'mhinz/vim-grepper', { 'on': ['Grepper', '<plug>(GrepperOperator)'] }
```

The `on` condition lists the two entry points that trigger loading, the `:Grepper` command and the operator plug. That is a sensible lazy-load key for this plugin, because the plugin is only useful when you actually search, and the two entry points are the complete set of ways to reach it.

The plugin works with Vim and Neovim on Unix-like systems, and is mostly working on Windows as well, with the findstr tool in the list being the reason Windows support is plausible at all.

## Quickfix or location list, and a demo that shows the difference

The results go into a quickfix or location list, and the project ships two demo animations that show what each is for.

The general usage demo shows the normal case, a search across the project with the results collected for stepping through. The second demo is the more interesting one, because it greps only files currently loaded in Vim. That is a genuinely different search from the default one, and it is a different question: instead of asking what matches in the repository, it asks what matches in the buffers you have open right now, which is what you want when you are refactoring and have a set of related files in front of you.

The quickfix list and the location list are the two Vim mechanisms for holding a list of results, and the plugin lets you use either. The quickfix list is the global one, shared across windows and reachable from anywhere, and the location list is per-window. For a search plugin the choice is mostly about workflow: the quickfix list persists and accumulates, so it is the right home for a set of results you want to come back to, while the location list is the right home for results that belong to one window's current context.

The project summary does not spell out which is the default, and the wiki pages linked for the prompt, the operator, the commands, and adding a tool are where that kind of detail lives. It also says the README is only the tip of the iceberg and that you should read `:h grepper` and the wiki to learn about every feature, which is the normal way Vim plugins are documented, with the help file as the reference and the wiki as the tutorial.

The example configurations are also in the wiki, on a page called example configurations and mappings, which is where you would look to see how a heavy user has wired the operator and the commands.

## Adding a tool is meant to be easy

Custom tools have their own wiki page, and the project summary makes a claim about both changing the behaviour of the default tools and adding new ones: changing the behaviour of the default tools is very easy, and so is adding new tools.

That matters because the supported tool list is a snapshot, not a limit. The tools named are the ones the author uses and the ones people ask for, but a grep-like tool that is not on the list is not excluded. A user with a wrapper script, a custom search, or a tool that only exists on their system can add it.

The structural reason this is easy is the one the commands section already reveals. Every per-tool command is built atop `:Grepper`, so the tool is a parameter rather than a separate code path. Adding a tool means telling the plugin how to invoke it and how to parse its output, and changing a default tool's behaviour means adjusting that same description. There is one place where the tool is defined rather than seven places where it is special-cased.

This is the kind of design decision that separates a plugin that ages well from one that accumulates patches. The tool list will change over time, new search tools appear, and the ones that matter to you are not necessarily the ones that matter to the author. A plugin whose architecture makes the tool a parameter lets each user adapt it without asking anyone.

The topics attached to the repository include async, findstr, git, grep, neovim, pt, rg, sift, ack, ag, vim, vim-plugin, viml, and viml-scripts, which is a reasonable summary of the surface the plugin covers.

## The author is closing the feature door, deliberately

There is a disclaimer in the project summary, and it is the most important sentence in the document for anyone considering depending on this plugin.

From the author's point of view it is feature-complete, so they will not add new features or put much time into reviewing complex PRs.

That is a much stronger statement than most open source projects make. It is not that the project is inactive, since the last push was on 2026-07-20 and there is a changelog and a contributing guide. It is that the author has decided what the plugin is and is not going to grow it. Bug fixes, compatibility work, and small contributions are fine. A new command, a new interaction mode, or a substantial refactor is not coming.

There is a practical implication for how you plan around it. If your workflow needs a capability that is not there today, and the plugin is not going to grow, then your options are to write the missing piece yourself, to fork the plugin, or to pick a different tool. That is a fine arrangement for a plugin that solves one problem completely, and a bad one for a plugin you were hoping to build on.

The project's own framing is consistent with that. The feedback section asks people to star the repository, calling it a great way of getting feedback, and says the same goes for reporting issues or feature requests. So the channel for telling the author what you want exists, but the disclaimer has already told you what the answer will be for anything that is a new feature.

The contact is a Twitter account, and the README links the wiki, so the community surface is there even if the roadmap is fixed.

## Where vim-grepper is the wrong tool

The limits are mostly about fit rather than about defects.

First, this is a search frontend, not a code navigation tool. It finds matching lines. It does not build a symbol index, it does not find callers, and it does not understand your language. If your workflow is jump-to-definition rather than find-matching-text, a language server is a different tool and a better one, and the two compose rather than compete.

Second, the tool choice is a real dependency. Whatever search tool you use has its own quirks, its own default excludes, and its own output format, and the plugin parses that output. If your tool's output format changes between versions, the plugin needs to change with it, and if the tool is one the author does not use, the parsing is on you when you add it. A grep implementation that ignores your .gitignore, or that follows it when you did not want it to, will produce results you did not ask for.

Third, the plugin is Vim and Neovim only, and on Windows it is described as mostly working. On Unix-like systems it works with both editors. A team that has standardised on a different editor gets nothing from it, and a Windows user should expect a rougher edge than a Linux user.

Fourth, the asynchronous design has a consequence worth knowing. Because the search runs in the background and the results arrive when they arrive, a search over a very large tree on a spinning disk, or over a directory with a huge number of files, can take a while, and the plugin does not report progress in a way the summary describes. You may find yourself starting a search, switching to another buffer, and coming back later to a result that is stale relative to what you have since edited.

Fifth, and this is the practical one, a grep tool that ignores .gitignore is often wrong for a search that is not about the repository. If you are searching a directory of logs, or a mounted data set, or the untracked files in a project, the default behaviour of the fastest tools will skip what you wanted. The plugin makes it easy to cycle through tools, and knowing which tool to pick for which question is the skill the plugin does not teach you.

## Conclusion

vim-grepper fits a Vim or Neovim user who searches a large codebase often, who already has a preferred search tool, and who wants the results without blocking the editor. It is the wrong choice for an editor where searching is not how you work, and it is the wrong choice if you need a feature that is not there yet, because the author states the plugin is feature-complete and will not be adding new features. Check three things before you install it: that the tool you want is on the list or is straightforward to add, since adding a new tool is documented as easy, that the way you want to invoke it matches the prompt or the operator workflow, and that you read the wiki, because the project says the README is only the tip of the iceberg and the full reference is in `:h grepper`.

## FAQ

### What does vim-grepper do and which search tools does it support?

It starts an asynchronous search with your favourite grep tool and puts all matches in a quickfix or location list. The supported tools are ag, ack, git grep, ripgrep, pt, sift, findstr, and plain grep, and adding a new tool is documented as easy.

### How do I install vim-grepper in Vim or Neovim?

With your favourite plugin manager, for example vim-plug, using `Plug 'mhinz/vim-grepper'`. If you prefer lazy loading, use `Plug 'mhinz/vim-grepper', { 'on': ['Grepper', '<plug>(GrepperOperator)'] }`, so the plugin loads when the command or the operator is used.

### What are the ways to start a search with vim-grepper?

The `:Grepper` command opens a prompt where you enter a query and can cycle through the list of tools, the operator uses the current visual selection to pre-fill the prompt or start searching right away, and per-tool commands such as `:GrepperGit` and `:GrepperAg` are built atop `:Grepper` and accept a wide range of flags.

### Is vim-grepper still getting new features?

The author states that from their point of view it is feature-complete, so they will not add new features or put much time into reviewing complex pull requests. The last push to the repository was on 2026-07-20, and the project asks for stars, issue reports, and feature requests as feedback.

## Sources

- [Issues](https://github.com/mhinz/vim-grepper/issues)
- [License: MIT](https://github.com/mhinz/vim-grepper/blob/master/LICENSE)
- [mhinz/vim-grepper on GitHub](https://github.com/mhinz/vim-grepper)
- [README](https://github.com/mhinz/vim-grepper/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mhinz-vim-grepper