Skip to main content



This module improves the performance of your web applications by compressing HTTP response bodies returned by your upstream service.

If an HTTP request includes an Accept-Encoding header, HTTP responses will be automatically compressed and a Content-Encoding response header will be added. If the response was already compressed by your upstream service, ngrok takes no action.

Example Usage

ngrok http 80 --compression


Streaming Compression

When ngrok performs compression, the response body is not buffered; the response body is compressed as it is streamed through the ngrok edge.

Algorithm Choice

If a request specifies Accept-Encoding but no requested values are supported, ngrok takes no action and the upstream response is returned without modification.

ngrok negotiates the encoding type as defined by the RFC for Accept-Encoding. It respects q-values and chooses the Accept-Encoding supported algorithm with the highest q-value.

ngrok supports the following compression algorithms in the Accept-Encoding header.


Response Headers

When ngrok performs compression, the following changes are made to the HTTP response header:

  • The Content-Length header is removed
  • A Content-Encoding header is added with the negotiated algorithm
  • A Vary: Accept-Encoding header is added

Compression Level

The compression level is a value which indicates whether the compression algorithm should prefer to save more space at the expense of being slower and using more compute. This value is not currently configurable. ngrok automatically chooses a value that provides a reasonable tradeoff.



This module does not support any configuration. It is either enabled or disabled.

Upstream Headers

This module does not add any upstream headers.


This module does not return any errors.


When this module is enabled, it populates the following fields in http_request_complete.v0 events.



Compression is an HTTPS Edge module which can be applied to Routes.


This module is available on all plans.

Try it out

For testing purposes, create a directory with a file in it and then enter that directory.

mkdir test-dir
cd test-dir
echo "hello world" > t.txt

ngrok can serve files from any directory (just like Python's Simple HTTP Server) by forwarding to a file:// URL. We're going to use that capability for our compression testing.

First let's see what this looks like without using compression by running the following in your test-dir directory:

ngrok http file://`pwd` --domain

Then in another terminal while ngrok is still running:

curl --compressed -D -
  • --compressed instructs curl to set the Accept-Encoding header to request compressed content
  • -D - instructs curl to show the HTTP response headers

You should get a response that looks like:

HTTP/2 200
content-type: text/html; charset=utf-8
date: Tue, 18 Jul 2023 09:52:49 GMT
last-modified: Tue, 18 Jul 2023 09:52:34 GMT
ngrok-trace-id: 24e925dd0f348c1040d7ff62b06606cd
content-length: 39

<a href="t.txt">t.txt</a>

Now let's try it again with compression. Stop your ngrok agent and restart it by changing the command to:

ngrok http file://`pwd` --domain --compression

Rerun the same curl command:

curl --compressed -D -

This time you should see that HTTP response headers include content-encoding: deflate indicating that the response was compressed.

HTTP/2 200
content-encoding: deflate
content-type: text/html; charset=utf-8
date: Tue, 18 Jul 2023 10:03:22 GMT
last-modified: Tue, 18 Jul 2023 09:52:34 GMT
ngrok-trace-id: b6b6cdce029e94123188ce53c0febee4
vary: Accept-Encoding

<a href="t.txt">t.txt</a>