Enable Bash Completion in Zsh on Linux

Zsh is the default shell on macOS and increasingly popular on Linux, but a large number of CLI tools only ship Bash completion scripts. If you have switched to Zsh and suddenly lost tab completion for tools like kubectl, docker, terraform, or git, the good news is that Zsh has built-in compatibility layers that let you load Bash completion scripts directly. This guide covers every method – from manual configuration to Oh My Zsh plugins.

How Zsh Completion Works

Zsh has its own completion system called compsys, initialized with the compinit function. It is more powerful than Bash completion, supporting descriptions, grouping, and context-aware suggestions. However, many tools only provide completion scripts written for Bash’s complete and compgen builtins.

To bridge this gap, Zsh provides bashcompinit – a compatibility function that emulates Bash’s completion interface inside Zsh. Once loaded, you can source Bash completion scripts and they work as expected.

Prerequisites – Install bash-completion

The bash-completion package provides the framework and a library of completion scripts for common commands. Install it even if you use Zsh, because many tools depend on its helper functions.

# RHEL / Rocky / AlmaLinux
sudo dnf install bash-completion

# Ubuntu / Debian
sudo apt install bash-completion

# Arch Linux
sudo pacman -S bash-completion

Verify the installation:

rpm -q bash-completion    # RHEL-family
dpkg -l bash-completion   # Debian-family

Manual Setup – compinit and bashcompinit

If you manage your Zsh configuration manually (no framework), add the following to your ~/.zshrc:

# Initialize Zsh completion system
autoload -Uz compinit && compinit

# Load Bash completion compatibility
autoload -Uz bashcompinit && bashcompinit

The order matters. Load compinit first, then bashcompinit. After these two lines, you can source any Bash completion script and it will register properly.

Reload your shell to apply:

source ~/.zshrc

Sourcing Individual Bash Completion Scripts

Once bashcompinit is loaded, add source lines for the tools you need. Here are examples for the most commonly requested ones.

kubectl

kubectl can generate its own completion script for both Bash and Zsh. For Zsh, use the native output:

# Add to ~/.zshrc
source <(kubectl completion zsh)

If you get errors about compdef not being found, make sure compinit is loaded before this line. To speed up shell startup, you can dump the output to a file:

kubectl completion zsh > ~/.zsh/completions/_kubectl

Then add ~/.zsh/completions to your fpath before calling compinit:

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

Docker

Docker ships Zsh completions with the package on most distributions. They are typically installed to /usr/share/zsh/vendor-completions/. If they are not loading automatically, check the path is in your fpath:

echo $fpath | tr ' ' '\n' | grep zsh

If Docker completions are missing, generate them:

mkdir -p ~/.zsh/completions
docker completion zsh > ~/.zsh/completions/_docker

Git

Git's Zsh completion is usually installed with the git package. It should work out of the box once compinit is loaded. If it does not, the completion file is typically at /usr/share/zsh/site-functions/_git. Ensure that directory is in your fpath.

Terraform

Terraform provides a built-in completion installer:

terraform -install-autocomplete

This appends the necessary lines to your ~/.zshrc. If you prefer manual control, use the Bash completion via bashcompinit:

# Add to ~/.zshrc after bashcompinit
complete -o nospace -C /usr/bin/terraform terraform

Verify completion works:

terraform pl[TAB]
# Should complete to: terraform plan

Using Oh My Zsh Plugins

If you use Oh My Zsh, many completion setups are handled by plugins. Edit your ~/.zshrc and add the relevant plugins to the plugins array:

plugins=(
  git
  docker
  docker-compose
  kubectl
  terraform
  ansible
  aws
  gcloud
)

Oh My Zsh loads compinit automatically, so you do not need to call it manually. Each plugin adds the appropriate completion definitions and sometimes useful aliases.

After editing, reload:

source ~/.zshrc

To see what a plugin provides, check its directory:

ls ~/.oh-my-zsh/plugins/kubectl/

Loading All Bash Completions at Once

If you want to load all available Bash completion scripts (for every tool that ships one), add this block after bashcompinit in your ~/.zshrc:

autoload -Uz compinit && compinit
autoload -Uz bashcompinit && bashcompinit

# Source all bash completions
if [ -d /usr/share/bash-completion/completions ]; then
  for f in /usr/share/bash-completion/completions/*; do
    [ -f "$f" ] && source "$f" 2>/dev/null
  done
fi

Be aware that sourcing every completion script adds to shell startup time. On a system with hundreds of installed tools, this can add a noticeable delay. A better approach is to source only the specific completions you actually use.

Speeding Up compinit

The compinit function scans all completion files on every shell startup. On systems with many completions, this takes time. To cache the scan results and only regenerate once per day:

autoload -Uz compinit
if [ "$(find ~/.zcompdump -mtime +1 2>/dev/null)" ] || [ ! -f ~/.zcompdump ]; then
  compinit
else
  compinit -C
fi

The -C flag skips the security check and uses the cached dump file, cutting startup time significantly.

Troubleshooting

If completions are not working after setup, check these common issues:

• compinit not loaded - Run which compinit in your shell. If it returns nothing, add the autoload line.
• Stale cache - Delete ~/.zcompdump and restart your shell. This forces a full rescan.
• Wrong fpath - Print your fpath with echo $fpath | tr ' ' '\n' and make sure the directory containing your completion files is listed.
• Order of operations - The fpath must be set before compinit is called. If you add completion files to a custom directory, add that directory to fpath first.

Summary

Zsh handles Bash completions well through bashcompinit. For most popular DevOps tools, native Zsh completion scripts exist and work better than the Bash compatibility layer. Use Oh My Zsh plugins when available, generate and cache completion files for tools like kubectl and docker, and keep your compinit setup efficient. With the configuration covered here, your Zsh shell will have full tab completion for every tool you work with.