Axios decompress false in Node.js Explained

Setting decompress: false in the Axios configuration for Node.js disables the client's automatic decompression of HTTP response bodies. By default, Axios requests compressed data (such as gzip, deflate, or brotli) from the server and decompresses it transparently before returning the response. Disabling this option ensures the response payload remains in its raw, compressed format, which is particularly useful for proxying responses, saving compressed files directly to disk, and reducing CPU overhead.

Default Behavior vs. decompress: false

In a Node.js environment, Axios behaves differently based on this setting:

• Default (decompress: true): Axios automatically adds the Accept-Encoding: gzip, compress, deflate, br header to the outgoing request. When the server responds with a compressed body and a matching Content-Encoding header, Axios uses Node's internal zlib module to decode the payload. The response.data you receive is fully decompressed (e.g., parsed JSON or a plain UTF-8 string).
• Disabled (decompress: false): Axios does not automatically decompress the response stream. If the server sends a compressed response, the raw, compressed bytes are preserved and returned in response.data as a Buffer or raw readable stream.

Direct Effects of Setting decompress: false

1. Payload Remains Compressed: The received data retains the encoding applied by the server (e.g., gzip or br). Attempting to read it as plain text without manual decompression will produce binary output.
2. Reduced CPU Usage: Because Node.js does not execute decompression algorithms on incoming data, CPU cycles and memory allocations are saved.
3. Preserved Response Headers: The Content-Encoding and Content-Length headers directly correspond to the raw payload received over the wire.

Common Use Cases

1. HTTP Proxying and Forwarding

When building an API gateway or reverse proxy in Node.js, decompressing a response only to recompress it for the client wastes CPU resources. Setting decompress: false allows you to pipe the compressed stream directly from the target server to the client without modifying the payload.

2. Downloading Compressed Files Directly to Disk

If you are downloading archives, pre-gzipped assets, or database dumps, you can stream the compressed data directly to a file via fs.createWriteStream() without spending resources decoding it in memory.

3. Custom Decompression Logic

If you need custom handling for specific compression algorithms, error recovery, or streaming transformations, setting decompress: false gives you total control over how and when the payload is decompressed.

Code Example

const axios = require('axios');
const fs = require('fs');

async function downloadRawCompressedFile() {
  const response = await axios.get('https://example.com/data.json', {
    responseType: 'stream',
    decompress: false, // Disables automatic decompression
    headers: {
      'Accept-Encoding': 'gzip'
    }
  });

  // Pipe the raw gzip stream directly to a file
  const writer = fs.createWriteStream('data.json.gz');
  response.data.pipe(writer);
}

By disabling automatic decompression, Axios shifts the responsibility of payload handling to your application, optimizing performance when raw data transfer is preferred.