How to Curl URLs with Special Characters and Spaces

Using curl to send requests to URLs containing spaces, ampersands, question marks, or brackets often results in command-line errors because the shell misinterprets these characters. This article provides a direct guide on how to handle these special characters using quoting, percent-encoding, and native curl flags to ensure your API requests and web queries execute successfully.

1. Wrap the URL in Single Quotes

The simplest and most effective way to prevent your command-line shell (like Bash or Zsh) from misinterpreting special characters is to wrap the entire URL in single quotes (').

In Unix-like shells, characters like &, ?, *, and ; have special meanings. For example, & runs a command in the background. Single quotes force the shell to treat the entire string as a literal value.

curl 'https://api.example.com/search?query=hello&limit=5'

Note: Avoid using double quotes (") if your URL contains a dollar sign ($), as the shell will attempt to evaluate it as a variable.

2. Replace Spaces and Special Characters with Percent-Encoding

While quoting prevents shell errors, web servers still require URLs to be properly formatted according to RFC 3986 standards. Browsers do this automatically, but with curl, you must manually replace spaces and certain characters with their percent-encoded equivalents.

Common encodings include: * Space (): %20 or + * Ampersand (&): %26 (when used inside a parameter value) * Equals (=): %3D (when used inside a parameter value) * Percent (%): %25

Example with a space:

# Incorrect (causes a shell error or bad request)
curl 'https://api.example.com/files/my document.pdf'

# Correct (percent-encoded)
curl 'https://api.example.com/files/my%20document.pdf'

3. Use --data-urlencode for GET and POST Requests

If you want curl to handle the percent-encoding for you, use the --data-urlencode flag.

For GET Requests

Combine --data-urlencode with the -G (or --get) flag. This tells curl to append the encoded parameters to the end of the URL automatically.

curl -G --data-urlencode "query=special characters & spaces" 'https://api.example.com/search'

For POST Requests

For standard POST requests, omitting the -G flag will send the encoded data in the request body.

curl --data-urlencode "user=john doe" 'https://api.example.com/login'

4. Disable URL Globbing with -g

curl naturally supports “globbing,” which allows you to fetch multiple URLs using bracket and brace patterns (e.g., www.example.com/file[1-100].html). If your URL contains literal square brackets [] or curly braces {} as part of its query parameters, curl will throw an error.

To solve this, use the -g (or --globoff) option to turn off globbing.

curl -g 'https://api.example.com/items?ids=[101,102,103]'