# Gzip Compression

The `gzip` plugin compresses eligible HTTP response bodies before the gateway sends them to clients. It can reduce bandwidth for text, JSON, and other compressible content on selected routes or services without changing the upstream application.

## Response Eligibility[​](#response-eligibility "Direct link to Response Eligibility")

The plugin configures response compression when these conditions are met:

| Condition         | Behavior                                                                                                                                                                    |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client support    | The client advertises `gzip` with a nonzero quality value in `Accept-Encoding`.                                                                                             |
| Content type      | The response has `Content-Type`, and its MIME type matches `types`.                                                                                                         |
| Response length   | If the response includes a numeric `Content-Length`, it must be at least `min_length`. When `Content-Length` is absent, the plugin does not apply the minimum-length check. |
| HTTP version      | The client HTTP version is greater than or equal to `http_version`.                                                                                                         |
| Response status   | The response status is `200`, `403`, or `404`.                                                                                                                              |
| Existing encoding | The response does not already have a nonempty `Content-Encoding` header.                                                                                                    |
| Response body     | The response is a body-bearing main response.                                                                                                                               |

The gateway's static `gzip_proxied` and `gzip_disable` policies can still prevent compression. Compressing a response removes `Content-Length` and `Accept-Ranges` and converts a strong `ETag` to a weak validator.

## Examples[​](#examples "Direct link to Examples")

The examples first compare identity-encoded and gzip-encoded responses and verify that decompression preserves the response body. The second example raises the minimum length so that the same response is no longer compressed.

### Compress a Text Response[​](#compress-a-text-response "Direct link to Compress a Text Response")

The Docker-based setup uses a local plain-text upstream and requires a running APISIX or API7 Gateway container that can join a Docker network.

Create and enter a working directory for the example:

```
mkdir gzip-example

cd gzip-example
```

Create the following Python script for the test upstream:

gzip-upstream.py

```
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer





class Handler(BaseHTTPRequestHandler):

    protocol_version = "HTTP/1.1"



    def do_GET(self):

        if self.path != "/large-response":

            self.send_error(404)

            return



        body = b"compressible response\n" * 256



        self.send_response(200)

        self.send_header("Content-Type", "text/plain; charset=utf-8")

        self.send_header("Content-Length", str(len(body)))

        self.send_header("Vary", "Origin")

        self.end_headers()

        self.wfile.write(body)



    def log_message(self, *_):

        pass





ThreadingHTTPServer(("0.0.0.0", 8000), Handler).serve_forever()
```

Set `GATEWAY_CONTAINER` to the running APISIX or API7 Gateway container. Create a dedicated network and connect the gateway to it:

```
export GATEWAY_CONTAINER=replace-with-gateway-container-name



docker network create gateway-gzip-net

docker network connect gateway-gzip-net "$GATEWAY_CONTAINER"
```

Start the test upstream:

```
docker run -d \

  --name gzip-upstream \

  --network gateway-gzip-net \

  -v "$PWD/gzip-upstream.py:/gzip-upstream.py:ro" \

  python:3.13.15-alpine3.24 \

  python -u /gzip-upstream.py
```

Configure the plugin to compress sufficiently large plain-text responses and add the response-variance header.

If Admin API authentication is enabled, export an admin-role key as `ADMIN_API_KEY` before using the Admin API tab.

* Admin API
* ADC

Create the route:

```
curl "http://127.0.0.1:9180/apisix/admin/routes/gzip-route" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "uri": "/large-response",

    "plugins": {

      "gzip": {

        "types": ["text/plain"],

        "min_length": 100,

        "comp_level": 6,

        "vary": true

      }

    },

    "upstream": {

      "type": "roundrobin",

      "nodes": {

        "gzip-upstream:8000": 1

      }

    }

  }'
```

Configure ADC to connect to the target backend. The remaining ADC commands read the connection settings from these environment variables:

* APISIX
* API7 Gateway

If Admin API authentication is enabled, export an admin-role key as `ADMIN_API_KEY` before configuring ADC.

```
export ADC_BACKEND=apisix

export ADC_SERVER="http://127.0.0.1:9180"

export ADC_TOKEN="${ADMIN_API_KEY}"
```

```
export ADC_BACKEND=api7ee

export ADC_SERVER="https://{DASHBOARD_ADDR}"

export ADC_TOKEN="{DASHBOARD_TOKEN}"

export ADC_GATEWAY_GROUP="{GATEWAY_GROUP}"
```

Create the service and route:

adc.yaml

```
services:

  - name: gzip-service

    labels:

      docs-example: gzip

    routes:

      - name: gzip-route

        uris:

          - /large-response

        plugins:

          gzip:

            types:

              - text/plain

            min_length: 100

            comp_level: 6

            vary: true

    upstream:

      type: roundrobin

      nodes:

        - host: gzip-upstream

          port: 8000

          weight: 1
```

Preview the changes and confirm that they only affect resources for this example:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=gzip
```

Review `diff.yaml`, then synchronize the labeled service:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=gzip
```

Save an identity-encoded response and a gzip-encoded response:

```
curl "http://127.0.0.1:9080/large-response" \

  -H "Accept-Encoding: identity" \

  --silent \

  --show-error \

  --fail \

  --dump-header identity-headers.txt \

  --output identity.txt



curl "http://127.0.0.1:9080/large-response" \

  -H "Accept-Encoding: gzip" \

  --silent \

  --show-error \

  --fail \

  --dump-header gzip-headers.txt \

  --output response.gz
```

Confirm that the second response is gzip encoded and varies by the request encoding:

```
grep -i "^Content-Encoding:" gzip-headers.txt

grep -i "^Vary:" gzip-headers.txt
```

The gzip-encoded response includes both headers:

```
Content-Encoding: gzip

Vary: Origin

Vary: Accept-Encoding
```

The gateway preserves the upstream variance and adds request-encoding variance for caches.

Decompress the response and compare it with the identity-encoded body:

```
if ! gzip -dc response.gz > decompressed.txt; then

  echo "Decompression failed"

  exit 1

fi



if cmp identity.txt decompressed.txt; then

  echo "Bodies match"

else

  echo "Bodies differ"

  exit 1

fi



if [ "$(wc -c < response.gz)" -lt "$(wc -c < identity.txt)" ]; then

  echo "Compressed response is smaller"

else

  echo "Compressed response is not smaller"

  exit 1

fi
```

The checks return:

```
Bodies match

Compressed response is smaller
```

The results confirm that compression preserves the response body and reduces its size for the highly compressible test content.

### Skip Responses Below the Minimum Length[​](#skip-responses-below-the-minimum-length "Direct link to Skip Responses Below the Minimum Length")

Update the plugin from the previous example so that the test response is smaller than the configured minimum length:

* Admin API
* ADC

```
curl "http://127.0.0.1:9180/apisix/admin/routes/gzip-route" -X PATCH \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "plugins": {

      "gzip": {

        "types": ["text/plain"],

        "min_length": 10000,

        "comp_level": 6,

        "vary": true

      }

    }

  }'
```

In `adc.yaml`, increase the minimum length on the existing route:

adc.yaml (route plugin)

```
plugins:

  gzip:

    types:

      - text/plain

    min_length: 10000

    comp_level: 6

    vary: true
```

Preview the updated file:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=gzip
```

Review `diff.yaml`, then synchronize the labeled service:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=gzip
```

Request gzip encoding again and check whether the response includes `Content-Encoding`:

```
if ! curl --silent --show-error --fail \

  "http://127.0.0.1:9080/large-response" \

  -H "Accept-Encoding: gzip" \

  --dump-header min-length-headers.txt \

  --output /dev/null; then

  echo "Request failed" >&2

  exit 1

fi



if grep -qi "^Content-Encoding: gzip" min-length-headers.txt; then

  echo "Unexpected compressed response"

  exit 1

else

  echo "Response is not compressed"

fi
```

The check returns:

```
Response is not compressed
```

The response is not compressed because its declared length is below the updated threshold.
