fzf-tab: fzf-based completion for zsh, and when it does not fit
Replace zsh's default completion selection menu with fzf!
At a glance
- What is it?
- fzf-tab replaces zsh's completion selection menu with fzf while leaving the underlying completion system untouched. It is a small plugin for people who already live in zsh, and it has real ordering constraints.
- Who is it for?
- Adopt fzf-tab if you already use zsh with compinit and fzf, and you want the completion list to be searchable, grouped and previewable without rewriting your completion setup. Skip it if you use bash or fish (the plugin is zsh only), or if you want a completion engine that works outside your interactive shell.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 164 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- Aloxaf/fzf-tab4,989 ★ · +50
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| Aloxaf/fzf-tab | 4.9k | 5k |
50 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The problem: zsh's completion menu is a list, not a search box
zsh's completion system, compsys, is thorough. It knows about variables, function names, the directory stack, in-word completion and hundreds of command-specific rules. What it does not give you is a way to type a few characters and filter a thousand candidates interactively, or to see a preview of what you are about to select. Pressing Tab twice on a large directory or a long option list produces a menu you scroll through with arrow keys.
fzf-tab targets exactly that gap. The README states the plugin does not do completion at all: it shows you the results of the default completion system through fzf. That distinction matters more than it sounds, because it means every zstyle rule, every completion function and every command-specific definition you already have keeps working. The plugin changes the selection UI, not the candidate source.
The audience is narrow and specific: zsh users who have already installed fzf and who are comfortable editing .zshrc. If you do not use zsh, the repository offers nothing, since the plugin is written in Shell for zsh and its keybindings are zle widgets.
How fzf-tab hooks into compsys without replacing it
The mechanism visible in the repository is widget interception. zsh binds Tab, which internally is the control character ^I, to a completion widget. fzf-tab binds its own widget to ^I and, by default, calls the widget that was previously bound to ^I to obtain the completion list. That list is then handed to fzf for display and filtering, and the accepted result is inserted back into the command line.
This explains the compatibility section of the README. Other plugins also bind ^I, including fzf's own shell/completion.zsh and the completion library in ohmyzsh. Because fzf-tab chains to the previous binding, most combinations work, but only if the chain is built in the right order. If fzf-tab is initialized before a plugin that does not handle the previous binding properly, the chain breaks. The README's remedy is blunt: fzf-tab should be the last plugin to bind ^I, and if you are unsure, put it at the end of your plugin list.
The repository layout reflects the same design. fzf-tab.plugin.zsh is the entry point, fzf-tab.zsh holds the main logic, lib/ contains supporting shell code, modules/ holds the optional binary module, and test/ contains the test suite that the GitHub Actions workflow runs. Nothing in the layout suggests a completion engine of its own.
Installing fzf-tab and a first real use
The README lists prerequisites before any install method. fzf must be installed. fzf-tab must be loaded after compinit but before plugins that wrap widgets, such as zsh-autosuggestions or fast-syntax-highlighting. Completions themselves should be configured before compinit.
The manual path clones the repository and sources the plugin entry point from .zshrc. The clone command below is copied from the README; adjust the destination if you keep plugins elsewhere.
git clone https://github.com/Aloxaf/fzf-tab ~/somewhereAfter cloning, the README says to add two lines to ~/.zshrc: initialize compinit, then source the plugin. Order matters, and this is the order the README gives.
autoload -U compinit; compinit
source ~/somewhere/fzf-tab.plugin.zshIf you use a plugin manager instead, the README gives one-line forms. Antigen and Zinit take a single command each.
antigen bundle Aloxaf/fzf-tabzinit light Aloxaf/fzf-tabOh-My-Zsh expects the repository in the custom plugins directory, with fzf-tab added to the plugin list afterwards.
git clone https://github.com/Aloxaf/fzf-tab ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/fzf-tabPrezto follows the same pattern against its contrib directory, with fzf-tab added to the module list in .zpreztorc.
git clone https://github.com/Aloxaf/fzf-tab $ZPREZTODIR/contrib/fzf-tabOpen a new shell and press Tab on a partial command. You should see fzf take over the selection instead of zsh's menu. If nothing changes, the load order is the first thing to check.
What the plugin actually gives you at the prompt
Once loaded, the usage instruction is one line: press Tab as usual. The README documents three keybindings. Ctrl+Space selects multiple results, and the binding is configurable through the fzf-bindings tag. F1 and F2 switch between groups, configurable through the switch-group tag. The forward slash triggers continuous completion, which the README notes is useful when completing a deep path, configurable through the continuous-trigger tag.
Three commands are exposed. disable-fzf-tab falls back to compsys, enable-fzf-tab turns the plugin back on, and toggle-fzf-tab flips the state. The README notes that toggle-fzf-tab is also a zle widget, so it can be bound to a key. That trio is the practical escape hatch: when completion misbehaves, disabling the plugin tells you in one step whether fzf-tab or your completion configuration is responsible.
Group support depends on a zstyle the README calls out specifically. Setting the descriptions format to '[%d]' enables groups, and the README warns not to use escape sequences such as '%F{red}%d%f' in that format because fzf-tab ignores them. Filename colorizing comes from setting list-colors to the value of LS_COLORS. Neither is automatic.
The configuration that most users end up writing
The README presents one configuration block as common, and it is worth reading as a list of dependencies rather than as decoration. Disabling sort for git checkout, enabling group descriptions, wiring LS_COLORS into list-colors, and setting menu to no so that fzf-tab can capture the unambiguous prefix.
Preview commands are per-context. The README's example previews directory contents with eza when completing cd.
Tmux popups and the optional binary module
For tmux 3.2 and newer, the repository ships a script called ftb-tmux-popup. Pointing the fzf-command tag at it makes completion render in a tmux popup instead of inline. The README notes the script also works outside fzf-tab, with a pipe example: ls piped into ftb-tmux-popup. That makes it a standalone utility as much as a plugin component.
The binary module addresses a performance concern the README names directly. By default fzf-tab uses zsh-ls-colors to parse and apply ZLS_COLORS when the list-colors tag is set. That project is a pure zsh script, and the README states it is slow when there are too many files to colorize. Building the bundled module with build-fzf-tab-module speeds that path up, and the README says it is enabled automatically once built. Note the phrasing: the module accelerates colorizing, not completion itself. If you have not set list-colors, the module has nothing to do.
Where fzf-tab is the wrong tool
The load-order rule is the main failure mode, and it is not a bug you can patch around. fzf-tab has to be sourced after compinit and before widget-wrapping plugins, and it has to be the last plugin binding ^I. Get that ordering wrong and completion degrades in ways that look like a broken zsh rather than a broken plugin. The README's own instruction for the confused case is to move fzf-tab to the end of the plugin list.
A second limitation is scope. Because the plugin is zsh-specific, anyone working across bash, fish or a remote shell without zsh gets no benefit, and the README offers no cross-shell story. Related work exists in a different project, lincheney/fzf-tab-completion, which the README lists under related projects and which covers zsh, bash and GNU readline applications. If your problem is completion inside a REPL or a bash session, fzf-tab is not the answer.
Third, the plugin inherits whatever compsys produces. If a command has poor completion definitions, fzf-tab presents those poor results in a nicer interface. It improves selection, not candidate quality, and the README is candid about that division of labour.
Alternatives and the actual difference in approach
The nearest alternative named in the README is lincheney/fzf-tab-completion. The difference is architectural. fzf-tab is a zsh plugin that intercepts the ^I widget and delegates to compsys, so it only exists inside zsh and only works with zsh's completion definitions. fzf-tab-completion targets zsh, bash and GNU readline applications, which means it has to solve completion for shells and programs that do not share compsys. If you need one completion experience across several shells, the second project is the one to look at; if you want your existing zsh completion configuration preserved exactly, fzf-tab's delegation model is the reason it works everywhere in zsh, including variables, function names, the directory stack and in-word completion.
A second comparison is simply zsh's built-in menu completion, which requires no plugin, no fzf binary and no ordering rules. It is slower to filter and has no preview, but it cannot break your Tab binding. The trade is interface quality against setup fragility, and that is the honest way to frame the choice.
Maintenance, licence and upgrade cost
The repository is not archived, and the last push was on 2026-06-04. The most recent tagged release is v1.3.0 from 2026-03-16, preceded by v1.2.0 in February 2025 and v1.1.2 in May 2024. That cadence suggests a project that is maintained but not churning, with roughly a year between minor releases. There is no homepage listed, so the repository and its wiki are the documentation surface.
The licence is MIT, which is permissive and places few obligations beyond retaining the copyright and permission notice. That is a statement about the licence text, not legal advice; if you redistribute the plugin inside a product, read the LICENSE file in the repository root yourself.
Upgrade cost is low in the normal case, because the plugin is a set of zsh files you source. The risk sits in the interaction surface: zstyle definitions, fzf flag choices and plugin ordering are yours, and a newer fzf-tab version can change how those interact. That is why pinning a tag rather than tracking master is a reasonable default for a shell you depend on daily.
Editorial conclusion
Adopt fzf-tab if you already use zsh with compinit and fzf, and you want the completion list to be searchable, grouped and previewable without rewriting your completion setup. Skip it if you use bash or fish (the plugin is zsh only), or if you want a completion engine that works outside your interactive shell. Verify first that fzf is installed, that compinit runs before the plugin is sourced, and that fzf-tab is the last plugin to bind Tab; if completion stops appearing, run disable-fzf-tab to confirm where the fault sits.
Frequently asked questions
What is fzf-tab?
It is a zsh plugin that replaces the default completion selection menu with fzf. The README states it does not perform completion itself; it displays the results produced by zsh's default completion system.
How do I install fzf-tab?
Install fzf first, then load fzf-tab after compinit but before plugins that wrap widgets. The README gives manual, Antigen, Zinit, Oh-My-Zsh and Prezto instructions; the manual route clones the repository and sources fzf-tab.plugin.zsh from .zshrc.
How do I use fzf-tab?
Press Tab as usual. Ctrl+Space selects multiple results, F1 and F2 switch between groups, and the forward slash triggers continuous completion for deep paths. The disable-fzf-tab, enable-fzf-tab and toggle-fzf-tab commands control the plugin state.
What is the difference between fzf-tab completion and zsh autocomplete?
zsh autocomplete is the completion system itself, which generates candidates. fzf-tab leaves that system in place and only changes how the candidate list is presented, handing it to fzf for interactive filtering. The README notes this is why it works for variables, function names, the directory stack and in-word completion.
What is a fzf-tab alternative for bash or fish?
fzf-tab is zsh only. The README lists lincheney/fzf-tab-completion as a related project, which provides fzf tab completion for zsh, bash and GNU readline applications.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/aloxaf-fzf-tab)Star history chart for your README
[](https://hysenlabs.com/projects/aloxaf-fzf-tab)Was this useful?