How to Fix zsh: no matches found When Running a curl Command

If you’re a developer or system administrator who uses the Zsh shell, you’ve likely encountered the frustrating “zsh: no matches found” error.

This issue frequently appears when using the curl command with URLs that contain special characters, leaving many users who have switched from Bash confused.

This comprehensive guide will not only show you how to fix this common error but also explain why it happens, empowering you to handle any command-line situation with confidence.

The Root Cause: Zsh’s Powerful (But Strict) Globbing

The “zsh: no matches found” error doesn’t come from curl itself. It comes directly from the Zsh shell. The culprit is a feature called globbing (also known as filename expansion).

When you type a command, Zsh scans it for special characters like ?, *, and [] before the command is even executed. It interprets these as wildcards to match filenames in your current directory.

• ? matches any single character.
• matches any sequence of characters.

Consider a curl command with a typical URL containing query parameters:

curl <http://example.com/api/search?query=test>

Zsh sees the ? in the URL and immediately tries to find a file in the current directory named http://example.com/api/search followed by any single character. If it doesn’t find a matching file, it stops and reports the error: zsh: no matches found: <http://example.com/api/search?query=test>. The curl command never even gets a chance to run.

This behavior is a key difference from the Bash shell, which, in its default configuration, will simply pass the un-matched string along to the command if it doesn’t find a file.

---

Solution 1: The Quickest & Best Fix – Quote Your URL

The simplest and most recommended way to prevent Zsh from interpreting your URL is to wrap it in quotes. This tells the shell to treat the entire string as a single, literal argument and pass it directly to curl.

See also: Mastering the Linux Command Line — Your Complete Free Training Guide

You can use either single or double quotes, but single quotes are generally safer for URLs.

Using Single Quotes (Recommended)

Single quotes (') prevent the shell from interpreting any special characters within them. This is the most reliable method.

Incorrect command:

curl http://example.com/api/search?user=test&limit=5

Correct command:

curl 'http://example.com/api/search?user=test&limit=5'

By wrapping the URL in single quotes, Zsh hands the entire, unmodified string to curl, and your command works as expected.

Using Double Quotes

Double quotes (") also prevent globbing but still allow for shell expansion (e.g., for variables like $USER). While this works for most curl commands, it can lead to unexpected behavior if your URL contains characters like the dollar sign ($).

Correct command:

curl "http://example.com/api/search?user=test&limit=5"

Rule of Thumb: When in doubt, use single quotes for URLs.

---

Solution 2: Escaping Individual Characters

If you only have one or two special characters, you can “escape” them by prepending a backslash (\). This tells Zsh to treat the immediately following character as a literal character, not a wildcard.

Incorrect command:

curl http://example.com/api/search?user=test

Correct command:

curl http://example.com/api/search\?user=test

This is a clean way to handle the issue without needing to quote or escape the URL itself.

While this works, it can become cumbersome for URLs with multiple special characters (like ?, &, []), and it’s easy to miss one. Quoting is almost always a cleaner solution.

Solution 3: The noglob Prefix (A Command-Specific Fix)

Zsh provides a powerful keyword, noglob, which disables the globbing mechanism for a single command. You simply place it right before the command you want to run.

noglob curl http://example.com/api/search?user=test&limit=5

---

Permanent Solutions (Use with Caution)

If you find yourself constantly battling this issue with curl or other commands, you might consider a more permanent solution.

Creating a noglob Alias

You can create an alias in your Zsh configuration file (~/.zshrc) to automatically apply the noglob prefix every time you run curl.

1. Open your ~/.zshrc file in a text editor:
   

   nano ~/.zshrc
   
   

   
   
2. Add the following line to the file:
   

   alias curl='noglob curl'
   
   

   
   
3. Save the file and reload your Zsh configuration:
   

   source ~/.zshrc
   
   

   
   

Now, every time you type curl, Zsh will automatically run noglob curl, and you will no longer need to quote your URLs for this specific command.

Disabling the nomatch Option (Not Recommended)

It is possible to make Zsh behave like Bash by disabling its strict error checking for failed globbing attempts. This is done by unsetting the NOMATCH option.

To do this, add the following line to your ~/.zshrc file:

unsetopt NOMATCH

Warning: While this will “fix” the curl issue, it is generally discouraged. The “no matches found” error is a useful feature that can prevent dangerous mistakes with other commands (like rm or mv) by alerting you when a wildcard pattern doesn’t match what you intended. Disabling it removes this safety net.

Conclusion

The “zsh: no matches found” error is a common hurdle for those new to Zsh, but it stems from a powerful feature designed to make the shell safer and more predictable. For day-to-day use with the curl command, the best practice is simple:

Always wrap your URLs in single quotes.

This method is safe, explicit, and quickly becomes second nature. By understanding why the error occurs and knowing the different ways to solve it, you can take full control of your command-line experience.