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.
- 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]' - 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" - 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.
- Open your Zsh configuration file in a terminal text editor:
nano ~/.zshrc - Scroll to the end of the file and add the following line:
unsetopt nomatch - Save the file by pressing
Ctrl + O, press Enter, and exit withCtrl + X. - Apply the changes immediately to your current terminal session:
source ~/.zshrc - 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.
- Open
~/.zshrc:nano ~/.zshrc - Add the
noglobprefix alias for common developer utilities:alias pip='noglob pip' alias pip3='noglob pip3' alias curl='noglob curl' alias wget='noglob wget' - Save and reload:
source ~/.zshrc - 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.
- Prefix the command line with
noglob:noglob git commit -m "Fix issue [BUG-104]" - 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.