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
- Open a terminal. Press
Ctrl+Alt+T(or your distro’s shortcut) to launch the terminal. - Verify curl is installed. Run
curl --version. If you see version info, you’re ready. If not, install it: on Debian/Ubuntu usesudo apt install curl; on Fedora/RHEL usesudo dnf install curl; on Arch usesudo pacman -S curl. - 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. - Save the output to a file. Use
-oto 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. - Follow redirects. Many URLs redirect (e.g., HTTP to HTTPS). Add
-Lto follow them:curl -L https://example.com. - Show response headers. Use
-ito include headers in the output, or-Ito fetch only the headers (HEAD request). Example:curl -I https://example.com. - Send a POST request with data. Use
-dto send form data:curl -d "name=John&age=30" https://example.com/api. By default, this sends a POST request with content-typeapplication/x-www-form-urlencoded. - Send JSON data. Use
-Hto set a custom header and-dfor the JSON body:curl -H "Content-Type: application/json" -d '{"name":"John"}' https://example.com/api. - 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. - Upload a file. Use
-Ffor multipart form data:curl -F "file=@/path/to/file" https://example.com/upload. - Set a timeout. Use
--max-timeto limit total time (in seconds):curl --max-time 10 https://example.com. This prevents hanging. - Use a proxy. If you’re behind a proxy, set it with
-x:curl -x http://proxy.example.com:8080 https://example.com. - Verbose output for debugging. Add
-vto see detailed information about the request and response:curl -v https://example.com. This shows TLS handshake, headers, and more. - 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
-dwith GET requests.-dforces POST. If you need query parameters, append them to the URL or use--getwith-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
-oand-O.-orequires a filename;-Ouses 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
-Ooptions:curl -O URL1 -O URL2. - For large downloads, use
-C -to resume an interrupted transfer. - Test APIs with
--data-urlencodeto properly encode special characters in data. - Use
--limit-rateto 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
- Windows 11 Calendar Wrong Day? Fix It Here
- Install ChromeOS: Convert Laptop to Chromebook
- Fix OneNote App Not Working on Android
- Move Games to SSD Without Reinstalling
- Move Windows 11 Taskbar to Top or Side: Easy Steps
- How to Log Out of X (Twitter) on iPhone, Android & PC