Helicon Ape



mod_gzip allows you to use GZIP compression method to significantly reduce the size of web page to be sent over HTTP protocol.

The module provides Apache mod_gzip compatible configuration but unlike Apache it uses 100% managed code.

All mod_gzip directives are inheritable. It means a child context can override parent value, but if there isn't any configuration for specified directive in the child context, parent value will be taken.

Quick start

The configuration below demonstrates how to enable compression for text, bmp & javascript files

SetEnvIfNoCase mime text/.* gzip=9
SetEnvIfNoCase mime image/bmp gzip
SetEnvIfNoCase mime application/x-javascript gzip

3 ways to enable mod_gzip

Below are the simplest configurations that enable mod_gzip and allow compression:

1) Standard mod_gzip directives

# Enable the module
mod_gzip_on yes 

# Allow GZIP compression for all requests 
mod_gzip_item_include mime .?

2) Environment variables

# That thing switches on the compression with default level 6
SetEnv gzip

3) Using mod_filter

# That thing switches on the compression with default level 6
FilterChain gzip

Managing mod_gzip using environment variables

Functionality implemented in Helicon Ape mod_env & mod_setenvif modules allows to manipulate mod_gzip with ease and convenience. Practically, you can manage and configure the module via environment variables not using it's standard directives at all. mod_setenvif extended syntax empowers you to perform subtle adjustment with only one 'but' - you don't need Apache compatibility.

Here's the list of environment variable with explanation of their purpose

gzip — enables mod_gzip module and allows compression. This variable may also be used to set compression level (see mod_gzip_compression_level directive):

SetEnv gzip 
SetEnvIf mime image/bmp gzip=9

The above example enables mod_gzip compression for all requests with default compression level, but for bmp images compression is set to maximum.

Note! gzip environment variable is not supported in Apache!

gzip-only-text/html — compression will be enabled only for the files with MIME type of text/html (i.e. for HTML pages). Prior to using this variable mod_gzip module must be enabled. Example:

BrowserMatch ^(?!Netscape).* gzip=9 gzip-only-text/html

In this example for all User-Agents except Netscape for requests to HTML pages GZIP will be enabled with maximum compression level (9). Presence of gzip variable is necessary.

no-gzip — prohibits GZIP application.

dont-vary — prohibits setting of Vary header. Be very attentive when using this variable as Vary header affects caching operation.

Ready-to-use preset for caching and compression

mod_gzip and mod_cache working together may have jolly positive impact on server performance. mod_gzip reduces the size of content and mod_cache decreases time of its delivery to the client. We have combined the most frequent situations of these modules' application into one config. You may use it on your server as is (without any modifications) but remember - Apache does not fully support this syntax .

# By file extension
SetEnvIfNoCase request_uri \.mdb$ gzip=9 
SetEnvIfNoCase request_uri \.bmp$ gzip cache-enable=mem
SetEnvIfNoCase request_uri \.(?:jpg|gif|png|swf|avi|rm)$ no-gzip                           

# By MIME type
SetEnvIfNoCase mime text/.* gzip=9 cache-enable=mem
SetEnvIfNoCase mime audio/wav gzip cache-enable=mem
SetEnvIfNoCase mime image/bmp gzip cache-enable=mem
SetEnvIfNoCase mime message/rfc822 gzip

SetEnvIfNoCase mime application/msword gzip
SetEnvIfNoCase mime application/postscript gzip
SetEnvIfNoCase mime application/vnd.ms-excel gzip
SetEnvIfNoCase mime application/vnd.ms-powerpoint gzip
SetEnvIfNoCase mime application/vnd.ms-works gzip
SetEnvIfNoCase mime application/x-javascript gzip cache-enable=mem
SetEnvIfNoCase mime application/x-msaccess gzip
SetEnvIfNoCase mime application/pdf gzip

# Exceptions for old browsers
#BrowserMatchNoCase \bOpera(?:\s5\.|/5) and mime application/.* no-gzip vary-agent !cache-enable
#BrowserMatchNoCase \bMozilla/4\.[67] and (mime application/.* or mime image/.*) no-gzip vary-agent !cache-enable
#BrowserMatchNoCase \bNetscape(?:6/6\.|/) and mime application/.* no-gzip vary-agent !cache-enable
#BrowserMatchNoCase \bFirefox/1 and mime application/pdf no-gzip vary-agent !cache-enable

SetEnvIfNoCase (mime text/css) or (mime image/jpeg) vary-agent
BrowserMatchNoCase \bMSIE\s[567]\. and (mime text/css or mime image/jpeg) no-gzip vary-agent !cache-enable

# Vary header should be properly set for caching
Header merge Vary User-Agent env=vary-agent

# Set expiry delta for static content.
# Dynamic pages should set expiry delta by oneself.
Header merge Cache-Control max-age=86400 env=cache-enable


You may use mod_log_config functionality to log mod_gzip activity. 4 module notes are supported:

  • %{mod_gzip_result}n - returns 'raw' if mod_gzip hasn't processed the request and 'compressed' if it has
  • %{mod_gzip_input_size}n - input size of content in bytes (before GZIP)
  • %{mod_gzip_output_size}n - output size of content in bytes (after GZIP)
  • %{mod_gzip_compression_ratio}n - the percentage of saved content

Each module note contains information relevant for one request only.


CustomLog "logs/mod_gzip.log" %h %u %t \"%V %r\" %s \
    mod_gzip: %{mod_gzip_result}n In:%{mod_gzip_input_size}n Out:%{mod_gzip_output_size}n\
    = %{mod_gzip_compression_ratio}n pct."

Related articles and topics

Enviroment variables

Name Context Description
gzip S V D .h enables mod_gzip module and allows compression
gzip-only-text/html S V D .h compression will be enabled only for the files with MIME type of text/html (i.e. for HTML pages)
no-gzip S V D .h prohibits GZIP application
no-dont-vary S V D .h prohibits setting of Vary header


Name Context Description
mod_gzip_on S V D .h enables mod_gzip for the current context
mod_gzip_compression_level S V D .h sets compression level
mod_gzip_add_header_count S V D .h writes statistical information for each request to error.log
mod_gzip_item_include S V D .h specifies files to be compressed
mod_gzip_item_exclude S V D .h specifies files NOT to be compressed
mod_gzip_handle_methods S V D .h specifies which HTTP request methods must be handled
mod_gzip_send_vary S V D .h allows suppressing Vary header


mod_gzip_on directive enables or disables mod_gzip for the current context. mod_gzip module is disabled by default, so you have to use this directive to enable it.


mod_gzip_on yes|no


mod_gzip_on no

Please note that this directive does not guarantee GZIP content compression is enabled. mod_gzip requires some additional configuration, and browsers must be able to send correct Accept-Encoding header.


mod_gzip_on yes


mod_gzip_compression_level directive specifies what GZIP compression level will be used. The value must be between 1 (min compression) and 9 (max compression). Value 0 gives uncompressed data.


mod_gzip_compression_level value


mod_gzip_compression_level 6

If mod_gzip_compression_level directive isn't used in any context, default value will be taken. The default value is taken from ZLib and equals to 6 . Technically there are two compression algorithms and mod_gzip makes a choice depending on compression level value. Fast but less effective algorithm is used for 1..3 levels. Levels 4..9 use more effective one.

Compression efficiency directly depends on file type. E.g. images and video are usually compressed to the lesser extent than text files. With mod_gzip you can easily improve a compression performance as shown in the example below.


mod_gzip_compression_level 9 

# Set fast compression for images
<FilesMatch "\.(gif|jpe?g|png)$">
mod_gzip_compression_level 3


mod_gzip_add_header_count directive can be used for debugging purposes. It writes statistical compression information for each request to error.log file.


mod_gzip_add_header_count Yes|No


mod_gzip_add_header_count No

Here is error.log record example:

In: 802 Out: 340 Savings: 462 ( 57 pct ): URL /index.html

It shows input bytes count, output bytes count, total saved bytes, efficiency in percents and requested file.


mod_gzip_add_header_count yes


mod_gzip_item_include specifies files to be compressed.

mod_gzip doesn't compress all requested files by default. You have to specify which content must be compressed and which mustn't. mod_gzip_item_include and mod_gzip_item_exclude directives are used to customize compression settings. They allow you specify various conditions for mod_gzip. Both directives have similar syntax.


mod_gzip_item_include reqheader|uri|file|mime regex


  • The first argument can be one of these values:
    • reqheader — allows to build the condition based on the request headers
    • rspheader — allows to build the condition based on the response headers
    • file — allows to build the condition based on the requested file name
    • uri — allows to build the condition based on the requested URI. Please note that URI and file name are not the same thing
    • mime — allows to build the condition based on the MIME-type of the requested file
  • regex argument allows to apply regular expression depending on the first argument value


# This rule enables mod_gzip for HTML content
mod_gzip_item_include  mime  ^text/html$

# This rule enables mod_gzip for the Opera browser
mod_gzip_item_include  reqheader "^User-Agent: Opera.*"

# This rule enables mod_gzip for CSS and JavaScript files
mod_gzip_item_include file \.(?:css|js)$

# This rule enables mod_gzip if the request URI contains '/for-gzip'
mod_gzip_item_include uri /for-gzip


mod_gzip_item_exclude specifies files NOT to be compressed.


mod_gzip_item_exclude reqheader|uri|file|mime regex


mod_gzip_item_exclude directive has the same arguments as mod_gzip_item_include directive. But it is used to define content that must NOT to be compressed by mod_gzip.


# Special broken browsers which request for gzipped content 
# but they aren't able to handle it correctly
mod_gzip_item_exclude reqheader "User-agent: Mozilla/4.0[678]"

# Images (GIF etc., will rarely ever save anything)
mod_gzip_item_exclude mime ^image/

mod_gzip uses simple logic to determine whether response must be compressed:

  • it must match at least one include rule
  • it must NOT match any exclude rule


mod_gzip_handle_methods directive allows to specify which HTTP request methods must be handled by mod_gzip. Currently only GET and POST methods are supported.


mod_gzip_handle_methods GET POST


mod_gzip_handle_methods GET POST


# Enable mod_gzip only for GET method
mod_gzip_handle_methods GET


mod_gzip_send_vary directive allows suppressing Vary header. But please note that this may cause some caching issues.


mod_gzip_send_vary Yes|No


mod_gzip_send_vary Yes


# Disable 'Vary' header
mod_gzip_send_vary No