Performance

Compression

On this page

HTTP compression allows you to shrink the body of a response before it’s relayed to a client, which results in using less network bandwidth per request. This reduces latency from a client’s perspective.

Enable compression for responses Jump to heading

  1. In a frontend, backend, listen or defaults section, add the proper filter directive depending on the load balancer version:

    • HAProxy 3.4 and newer: Use filter comp-res. The examples in this section use this syntax.
    • HAProxy Enterprise all versions/HAProxy 3.3 and older: Use filter compression. This syntax is deprecated and will become unsupported in a future release.

  2. Add the compression algo directive and set it to one of the following:

    • deflate
    • gzip
    • identity
    • raw-deflate

    Example for HAProxy 3.4 and newer:

    haproxy
    backend web_servers
      filter comp-res
      compression algo gzip
    haproxy
    backend web_servers
      filter comp-res
      compression algo gzip

    Responses will be compressed only if they aren’t already compressed.

  3. Add a compression type directive, which specifies the media types to compress:

    haproxy
    backend web_servers
      filter comp-res
      compression algo gzip
      compression type text/css text/html text/javascript application/javascript text/plain text/xml application/json
    haproxy
    backend web_servers
      filter comp-res
      compression algo gzip
      compression type text/css text/html text/javascript application/javascript text/plain text/xml application/json

  4. Optional: Add a compression offload directive, which states that the load balancer will remove the Accept-Encoding header before forwarding a request to backend servers. This prevents the servers from performing compression, offloading that work to the load balancer. The compression offload directive may only be placed in frontend, listen, and backend sections:

    haproxy
    backend web_servers
      filter comp-res
      compression algo gzip
      compression type text/css text/html text/javascript application/javascript text/plain text/xml application/json
      compression offload
    haproxy
    backend web_servers
      filter comp-res
      compression algo gzip
      compression type text/css text/html text/javascript application/javascript text/plain text/xml application/json
      compression offload

Enable compression for requests Jump to heading

This section applies to:

  • HAProxy 2.8 and newer
  • HAProxy Enterprise 2.8r1 and newer
  • HAProxy ALOHA 15.5 and newer

Your web server must support request body compression

Does your web server support decompressing requests? Most don’t. This feature will work only if the server can decompress the request and you have enabled that feature.

You can also shrink the body of a request before it’s relayed to a backend server.

  1. In a frontend, backend, listen or defaults section, add the proper filter directive depending on the load balancer version:

    • HAProxy 3.4 and newer: Use filter comp-req to compress requests or filter comp-res to compress responses. The examples in this section use this syntax.
    • HAProxy Enterprise all versions/HAProxy 3.3 and older: Use the filter compression and compression direction directives. This syntax is deprecated and will become unsupported in a future release.

    Example for HAProxy 3.4 and newer:

    haproxy
    backend web_servers
      filter comp-req
      filter comp-res
    haproxy
    backend web_servers
      filter comp-req
      filter comp-res

  2. Add the compression algo directive and set it to one of the following:

    • deflate
    • gzip
    • identity
    • raw-deflate

    You can choose different compression algorithms for responses and requests:

    • For requests, add an algo-req directive.
    • For responses, add an algo-res directive.
    haproxy
    backend web_servers
      filter comp-req
      filter comp-res
      compression algo-req deflate 
      compression algo-res gzip
    haproxy
    backend web_servers
      filter comp-req
      filter comp-res
      compression algo-req deflate 
      compression algo-res gzip

    Responses and requests will be compressed only if they aren’t already compressed.

  3. Specify the media types to compress.

    • If you’re compressing requests, add a compression type-req directive.
    • If you’re compressing responses, add a compression type-res directive.

    You can specify different media types for requests and responses.

    haproxy
    backend web_servers
      filter comp-req
      filter comp-res
      compression algo-req deflate
      compression type-req application/json text/xml text/plain
      compression algo-res gzip
      compression type-res text/css text/html text/plain text/xml text/javascript application/javascript application/json
    haproxy
    backend web_servers
      filter comp-req
      filter comp-res
      compression algo-req deflate
      compression type-req application/json text/xml text/plain
      compression algo-res gzip
      compression type-res text/css text/html text/plain text/xml text/javascript application/javascript application/json

  4. Optional: Add a compression offload directive, which states that the load balancer will remove the Accept-Encoding header before forwarding a request to backend servers. This prevents the servers from performing compression, offloading that work to the load balancer. The compression offload directive may only be placed in frontend, listen, and backend sections:

    haproxy
    backend web_servers
      filter comp-req
      filter comp-res
      compression algo-req deflate
      compression type-req application/json text/xml text/plain 
      compression algo-res gzip
      compression type-res text/css text/html text/plain text/xml text/javascript application/javascript application/json
      compression offload
    haproxy
    backend web_servers
      filter comp-req
      filter comp-res
      compression algo-req deflate
      compression type-req application/json text/xml text/plain 
      compression algo-res gzip
      compression type-res text/css text/html text/plain text/xml text/javascript application/javascript application/json
      compression offload

Process-level settings Jump to heading

Add any of the following directives to the global section to customize compression:

Directive Description
maxcomprate <kb> Sets the maximum per-process input compression rate to a number of kilobytes per second. For each session, if the maximum is reached, the compression level will be decreased during the session. If the maximum is reached at the beginning of a session, the session won’t compress at all. If the maximum isn’t reached, the compression level will be increased up to tune.comp.maxlevel. A value of zero means there isn’t a limit. This is the default value.
maxcompcpuusage <percent> Sets the maximum CPU usage the load balancer can reach before stopping the compression for new requests or decreasing the compression level of current requests. It works like maxcomprate but measures CPU usage instead of incoming data bandwidth. The value is expressed in percent of the CPU used by the load balancer. A value of 100 disables the limit. The default value is 100. Setting a lower value will prevent the compression work from slowing the whole process down and from introducing high latencies.
tune.comp.maxlevel <level> Sets the maximum compression level. The compression level affects CPU usage during compression. Each session using compression initializes the compression algorithm with this value. The default is 1.

Set a minimum file size Jump to heading

This section applies to:

  • HAProxy 3.2 and newer
  • HAProxy Enterprise 3.2r1 and newer
  • HAProxy ALOHA 17.5 and newer

You can set a minimum file size for HTTP compression, compressing files only if they’re large enough to matter. By avoiding unnecessary compression work, you reduce CPU overhead. For instance, 1500 bytes is the default Ethernet Maximum Transmission Unit (MTU) size. A message that already fits into a single MTU will be transmitted quickly without needing compression.

  • For compressing responses, set compression minsize-res to a number of bytes.

    haproxy
    backend web_servers
      ...
      compression minsize-res 1500
    haproxy
    backend web_servers
      ...
      compression minsize-res 1500

  • For compressing requests, set compression minsize-req to a number of bytes.

    haproxy
    backend web_servers
      ...
      compression minsize-req 1500
    haproxy
    backend web_servers
      ...
      compression minsize-req 1500

See also Jump to heading

For complete syntax and usage information on compression, see Compression reference in the HAProxy Configuration Manual.

Do you have any suggestions on how we can improve the content of this page?

Previous page Caching Next page Overload protection
© 2026 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences