How to use compression when downloading with cURL

Requesting compressed HTTP responses reduces the amount of data transferred for text-heavy downloads such as JSON, HTML, CSS, and logs. Smaller transfers usually finish faster and consume less bandwidth on slow or metered links.

In cURL, --compressed adds an Accept-Encoding header for every response encoding the current build can decode. That commonly includes gzip and deflate, and some builds also advertise br or zstd. After the transfer, cURL expands the response before writing it to disk, so the saved file is the normal uncompressed body.

Saved header dumps are not rewritten after decoding, so Content-Encoding: gzip can still appear in the captured headers even though the local file is already plain text. Servers can also ignore the compression request and reply uncompressed, and raw compressed bytes require a normal request without --compressed.

1. Download the response with --compressed and save the headers separately from the body.

   $ curl --compressed --silent --show-error --dump-header response.headers --output daily-usage-summary.json https://downloads.example.net/reports/daily-usage-summary.json

   --dump-header keeps the returned metadata in a separate file, which makes it easier to confirm whether the server actually compressed the transfer.

2. Open the saved headers and confirm that the server replied with a content encoding.

   $ cat response.headers
   HTTP/2 200
   content-type: application/json
   content-encoding: gzip
   vary: Accept-Encoding
   content-length: 248

   The saved headers still show the original wire format, so Content-Encoding: gzip here does not mean the downloaded file is still gzip-compressed.

3. Read the saved file and confirm that cURL wrote the decoded body to disk.

   $ cat daily-usage-summary.json
   {"report_date":"2026-04-22","service":"edge-ingest","requests_ok":18421}

   A readable JSON, HTML, or text file is the normal end state after a successful --compressed download.

4. Trace the request with --verbose when the compression negotiation itself needs proof.

   $ curl --compressed --verbose --output /dev/null https://downloads.example.net/reports/daily-usage-summary.json
   ##### snipped #####
   > GET /reports/daily-usage-summary.json HTTP/2
   > Host: downloads.example.net
   > Accept: */*
   > Accept-Encoding: deflate, gzip
   >
   ##### snipped #####
   < HTTP/2 200
   < content-type: application/json
   < content-encoding: gzip
   < vary: Accept-Encoding
   < content-length: 248
   <
   ##### snipped #####

   The exact Accept-Encoding list depends on the local cURL build. Omit --compressed when another program must receive the original compressed bytes instead of the decoded file.