How to fix "conflicting Homebrew wrapper configuration" errors

If you see an error like this when running brew:

Error: conflicting Homebrew wrapper configuration!
HOMEBREW_FORCE_BREW_WRAPPER was set to /opt/workbrew/bin/brew
but `brew` was invoked by /bin/zsh.

Ensure you run /opt/workbrew/bin/brew directly (not /opt/homebrew/bin/brew)!

Manually setting your PATH can interfere with Homebrew wrappers.
Ensure your shell configuration contains:
  eval "$(/opt/workbrew/bin/brew shellenv)"
or that /opt/workbrew/bin comes before /opt/homebrew/bin in your PATH:
  export PATH="/opt/workbrew/bin:/opt/homebrew/bin:$PATH"

It means your shell's PATH has /opt/homebrew/bin ahead of /opt/workbrew/bin, so typing brew runs Homebrew directly instead of through the Workbrew wrapper. This guide walks you through fixing it.

Quick fix for the current terminal session#

Run this command to temporarily fix PATH for the rest of your terminal session:

eval "$(/opt/workbrew/bin/brew shellenv)"

This takes effect immediately but only lasts until you close the terminal. Follow the next section for a permanent fix.

Permanent fix#

The goal is to make sure /opt/workbrew/bin comes before /opt/homebrew/bin in your PATH. To do that, you need to find and fix the line in your shell configuration that is overriding the order.

Step 1: Identify your shell#

Run the following to confirm which shell you are using:

echo $SHELL

Most macOS users will see /bin/zsh. If you see /bin/bash, substitute ~/.zshrc with ~/.bashrc (or ~/.bash_profile) in the steps below.

Step 2: Find the conflicting line#

Open your shell configuration file and look for any line that adds /opt/homebrew/bin to your PATH after the Workbrew shellenv line. Common patterns include:

export PATH="/opt/homebrew/bin:$PATH"

eval "$(/opt/homebrew/bin/brew shellenv)"

path=(/opt/homebrew/bin $path)

These are often added by Homebrew's own installer, development tools, or version managers. To search your ~/.zshrc for them:

grep -n 'homebrew' ~/.zshrc

Also check ~/.zprofile, ~/.zshenv, and ~/.zlogin if you have them, as they can also modify PATH:

grep -rn 'homebrew' ~/.zprofile ~/.zshenv ~/.zlogin 2>/dev/null

Step 3: Fix the ordering#

Once you have found the conflicting line, you have two options.

Option A: Remove the conflicting line. If you already have eval "$(/opt/workbrew/bin/brew shellenv)" in your shell configuration, the /opt/homebrew/bin/brew shellenv line is redundant. Delete it.

Option B: Move the conflicting line above the Workbrew shellenv line. If you need the line for another reason (e.g. it sets variables beyond PATH), move it so it runs before the Workbrew shellenv eval. That way, Workbrew's shellenv will place /opt/workbrew/bin at the front of PATH last, ensuring it takes priority.

Step 4: Verify the fix#

Open a new terminal window and run:

which brew

You should see:

/opt/workbrew/bin/brew

If you still see /opt/homebrew/bin/brew, another file is overriding PATH. Repeat Step 2, checking all of ~/.zshrc, ~/.zprofile, ~/.zshenv, and ~/.zlogin.

If you cannot find the conflicting line#

If you are unable to locate which file is overriding PATH, you can append the Workbrew shellenv to the end of your ~/.zshrc so it always runs last:

printf '\neval $(/opt/workbrew/bin/brew shellenv)\n' >> ~/.zshrc

This ensures /opt/workbrew/bin is placed at the front of PATH regardless of what runs before it. Open a new terminal and verify with which brew as described above.

Frameworks and tools that commonly override PATH#

Some tools modify PATH in ways that can conflict with Workbrew. If you use any of the following, check their configuration blocks in your shell startup files:

• Oh My Zsh and other zsh frameworks that re-source shellenv
• nvm, pyenv, rbenv, asdf, or other version managers that prepend to PATH
• Homebrew's own installer, which may add an eval "$(/opt/homebrew/bin/brew shellenv)" line

In each case, make sure the tool's PATH modifications appear before eval "$(/opt/workbrew/bin/brew shellenv)" in your shell configuration.