How to Fix ‘zsh: no matches found’ Error in Linux

Switching from the classic Bash shell to Zsh (Z Shell) in Linux or macOS provides modern autocomplete, directory navigation, and theme customization. However, running a standard command involving square brackets, wildcards, or complex URLs only to be halted by the terminal error: ‘zsh: no matches found: [pattern]’ causes immediate confusion. In Bash, if a wildcard pattern or bracket expression does not match any local files, the shell passes the literal string directly to the target program. In Zsh, strict filename generation (globbing) treats any unmatched wildcard or bracket as a syntax failure and aborts execution before the command runs.

Why Does Zsh Return ‘no matches found’?

The error is caused by Zsh’s default shell option NOMATCH. It occurs in standard command workflows:

  • Square Brackets in Package Managers: Installing Python packages with extras via pip (e.g., pip install 'framework[all]') where Zsh interprets [all] as a character class search.
  • Query Parameters in cURL and Wget URLs: Downloading links containing question marks, ampersands, or brackets (e.g., curl https://api.site.com/data?id=1&filter=[active]).
  • Unquoted Wildcards (* and ?): Using wildcards in Git commands (e.g., git checkout HEAD~1*) or find commands when no local file satisfies the pattern.
  • Caret (^) Negation Syntax: Using the caret character in command strings where Zsh interprets it as filename negation globbing.

Step 1: Quote or Escape Problematic Arguments (Immediate Fix)

Wrapping arguments containing brackets or wildcards in quotation marks prevents Zsh from attempting file path expansion.

  1. For Python pip commands: Wrap package names with extras inside single or double quotes:
    # Fails with zsh: no matches found
    pip install requests[security]
    
    # Succeeds cleanly
    pip install 'requests[security]'
  2. For cURL and Wget downloads: Always enclose URLs containing query parameters in quotes:
    # Fails
    curl https://example.com/api?user=[admin]&page=1
    
    # Succeeds
    curl "https://example.com/api?user=[admin]&page=1"
  3. Using Backslash Escapes: You can also escape individual bracket characters with a backslash:
    pip install requests\[security\]

Step 2: Disable Strict Glob Matching Permanently via .zshrc

If you prefer Zsh to behave like Bash—passing the literal string to the executable if no file matches—disable the nomatch option.

  1. Open your Zsh configuration file in a terminal text editor:
    nano ~/.zshrc
  2. Scroll to the end of the file and add the following line:
    unsetopt nomatch
  3. Save the file by pressing Ctrl + O, press Enter, and exit with Ctrl + X.
  4. Apply the changes immediately to your current terminal session:
    source ~/.zshrc
  5. Now, any unmatched bracket or wildcard expression will pass cleanly to your commands without throwing error prompts.

Step 3: Disable Globbing for Specific Commands (Aliases)

If you want to maintain strict globbing for general file operations while exempting tools like pip, curl, or git, define selective aliases.

  1. Open ~/.zshrc:
    nano ~/.zshrc
  2. Add the noglob prefix alias for common developer utilities:
    alias pip='noglob pip'
    alias pip3='noglob pip3'
    alias curl='noglob curl'
    alias wget='noglob wget'
  3. Save and reload:
    source ~/.zshrc
  4. You can now type pip install package[extra] naturally without quotes.

Step 4: Use noglob for One-Off Execution

For commands where you have not defined an alias, prefix the command directly with noglob in the terminal.

  1. Prefix the command line with noglob:
    noglob git commit -m "Fix issue [BUG-104]"
  2. Zsh will disable pattern matching exclusively for that command instance.

Understanding Zsh globbing behavior and configuring unsetopt nomatch or noglob aliases eliminates pattern matching errors and restores a seamless command-line workflow.

Get the best tech tips delivered straight to your inbox.

Join thousands of readers mastering Apple, Google, Microsoft, and Linux.