Fixing Zsh Completion Security Warnings on macOS

TL;DR: If you’re getting zsh compinit: insecure directories and files warnings on macOS, add autoload -Uz compinit && compinit -u to your ~/.zshrc file. The -u flag tells zsh to skip security checks for Homebrew-managed completion files.

So there I was, opening a new terminal session and getting hit with this annoying warning:

zsh compinit: insecure directories and files, run compaudit for list.
Ignore insecure directories and files and continue [y] or abort compinit [n]?

Every. Single. Time.

If you’re a macOS user with Homebrew installed, you’ve probably seen this too. It’s one of those things that’s not breaking anything, but it’s annoying enough to finally fix on a Friday afternoon.

What’s Actually Happening?

The warning appears because zsh’s completion system is being overly cautious about file ownership. Here’s what’s going on:

• Homebrew installs completion files for various tools (brew, docker, gh, etc.)
• These files live in /usr/local/share/zsh/site-functions/ as symlinks
• They point to actual completion files in /usr/local/Homebrew/completions/zsh/
• The completion files are owned by your user account, not root
• zsh sees this and thinks “hmm, these files could be modified by a non-root user, that’s potentially insecure”

When I ran compaudit, it listed all the “problematic” files:

/usr/local/share/zsh/site-functions/_brew
/usr/local/share/zsh/site-functions/_colima
/usr/local/share/zsh/site-functions/_docker
/usr/local/share/zsh/site-functions/_flyctl
/usr/local/share/zsh/site-functions/_gh
# ... and more

The Wrong Way to Fix It

My first instinct was to try fixing the permissions and ownership:

sudo chmod -R 755 /usr/local/share/zsh
sudo chown -R root:admin /usr/local/share/zsh

But that didn’t work because these are symlinks pointing to Homebrew-managed files. The actual files are owned by your user account (as they should be), and changing that would break Homebrew’s ability to manage them.

The Right Way to Fix It

The solution is simpler than I thought. Just tell zsh to skip the security checks for completion initialization by using the -u (unsafe) flag:

autoload -Uz compinit && compinit -u

The -u flag tells compinit to initialize completions even when it detects “insecure” files. This is safe to use because:

1. The completion files are managed by Homebrew
2. They’re just completion scripts, not executable code that runs with elevated privileges
3. This is the recommended approach for Homebrew users

Making It Permanent

To make sure this runs every time you open a new terminal, add it to your ~/.zshrc file:

# Initialize zsh completions (suppress security warnings for homebrew-managed completion files)
autoload -Uz compinit && compinit -u

After adding this line, source your updated config:

source ~/.zshrc

Why This Solution is Safe

Using compinit -u might sound scary because of the “unsafe” flag, but it’s actually the standard solution for this common Homebrew setup. The security warnings are overly cautious for completion files that are:

• Non-executable scripts used only for tab completion
• Managed by a trusted package manager (Homebrew)
• Located in standard system directories

The Result

No more annoying warnings! Your terminal now starts cleanly, and tab completion works perfectly for all your Homebrew-installed tools.

This is one of those small quality-of-life improvements that makes your development environment just a bit more pleasant to use. Sometimes the simplest fixes are the most satisfying.