sodcalculator

10 Tech How-To

How to Use curl Command in Linux

Guide 10-50942 · Updated · Step by step

curl is a command-line tool for transferring data to or from a server using protocols like HTTP, HTTPS, FTP, and more. It’s built into most Linux distributions and is essential for testing APIs, downloading files, and debugging network connections. This guide walks you through the most common curl uses, from basic requests to handling headers and authentication.

What You’ll Need

  • A Linux system with curl installed (check with curl --version; install via your package manager if missing).
  • Basic familiarity with the terminal.
  • An internet connection for remote requests.

Step-by-Step

  1. Open a terminal. Press Ctrl+Alt+T (or your distro’s shortcut) to launch the terminal.
  2. Verify curl is installed. Run curl --version. If you see version info, you’re ready. If not, install it: on Debian/Ubuntu use sudo apt install curl; on Fedora/RHEL use sudo dnf install curl; on Arch use sudo pacman -S curl.
  3. Make a simple GET request. The most basic usage is curl https://example.com. This fetches the page and prints the HTML to your terminal.
  4. Save the output to a file. Use -o to specify a filename: curl -o example.html https://example.com. Use -O (capital O) to save with the remote file’s name: curl -O https://example.com/file.zip.
  5. Follow redirects. Many URLs redirect (e.g., HTTP to HTTPS). Add -L to follow them: curl -L https://example.com.
  6. Show response headers. Use -i to include headers in the output, or -I to fetch only the headers (HEAD request). Example: curl -I https://example.com.
  7. Send a POST request with data. Use -d to send form data: curl -d "name=John&age=30" https://example.com/api. By default, this sends a POST request with content-type application/x-www-form-urlencoded.
  8. Send JSON data. Use -H to set a custom header and -d for the JSON body: curl -H "Content-Type: application/json" -d '{"name":"John"}' https://example.com/api.
  9. Add authentication. For basic auth, use -u username:password: curl -u user:pass https://example.com/private. For token-based auth, use a header: curl -H "Authorization: Bearer TOKEN" https://example.com/api.
  10. Upload a file. Use -F for multipart form data: curl -F "file=@/path/to/file" https://example.com/upload.
  11. Set a timeout. Use --max-time to limit total time (in seconds): curl --max-time 10 https://example.com. This prevents hanging.
  12. Use a proxy. If you’re behind a proxy, set it with -x: curl -x http://proxy.example.com:8080 https://example.com.
  13. Verbose output for debugging. Add -v to see detailed information about the request and response: curl -v https://example.com. This shows TLS handshake, headers, and more.
  14. Combine options. You can chain options, e.g., curl -L -o output.html -v https://example.com.

Common Mistakes

  • Forgetting to quote URLs with special characters. URLs containing & or ? should be quoted: curl "https://example.com/search?q=test&page=1".
  • Not following redirects. Without -L, curl only fetches the initial response, which may be a 301/302 redirect. This can lead to empty or unexpected output.
  • Using -d with GET requests. -d forces POST. If you need query parameters, append them to the URL or use --get with -d.
  • Overlooking certificate errors. If you get SSL errors, don’t just use -k (insecure) without understanding the risk. Only use it for testing.
  • Mixing up -o and -O. -o requires a filename; -O uses the remote name. Using the wrong one can overwrite files unintentionally.

Tips

  • Use curl -s (silent) to suppress progress and error messages, useful in scripts.
  • Use curl -w "%{http_code}\n" to print the HTTP status code. Great for checking if a site is up.
  • To download multiple files, use multiple -O options: curl -O URL1 -O URL2.
  • For large downloads, use -C - to resume an interrupted transfer.
  • Test APIs with --data-urlencode to properly encode special characters in data.
  • Use --limit-rate to throttle download speed, e.g., curl --limit-rate 100K URL.

Troubleshooting

curl: command not found – Install curl as described in Step 2.

SSL certificate problem – This often happens with self-signed certificates. For testing, you can use -k (insecure), but for production, add the certificate to your trust store.

Connection timed out – Check your network connection, firewall, or proxy settings. Try using -v to see where it hangs.

Empty response – The server may be returning a redirect that you’re not following. Add -L. Also check if the URL is correct.

Permission denied when writing file – Ensure you have write permissions in the target directory. Use sudo only if necessary, or change directory.

Data not sent as expected – If you’re sending JSON, ensure you set the Content-Type header. If using -d, note that it strips newlines; use --data-binary for exact data.

Frequently Asked Questions

What is the difference between curl and wget?

curl is more feature-rich for API testing and supports many protocols and data transfer options. wget is simpler and better for recursive downloads and mirroring websites.

How do I download a file with a different name?

Use -o filename to specify the output filename. For example: curl -o myfile.zip https://example.com/file.zip.

How can I see the response headers only?

Use -I (capital i) to send a HEAD request and print headers only. For GET with headers, use -i.

How do I send a PUT or DELETE request?

Use -X PUT or -X DELETE. For example: curl -X PUT -d "data" https://example.com/resource.

How do I use a cookie with curl?

To send a cookie, use -b "name=value". To save cookies from a response, use -c cookies.txt. To use a cookie file, use -b cookies.txt.

How do I ignore SSL certificate errors?

Use -k (or --insecure). This bypasses certificate verification, but only use it for testing, not for sensitive data.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →