Content encoding

The Ktor client provides the ContentEncoding plugin that allows you to enable specified compression algorithms (such as gzip and deflate) and configure their settings.

This plugin provides the following functionality:

Sets the Accept-Encoding header with the specified quality value.
Optionally encodes request body.
Decodes content received from a server to obtain the original payload.

Add dependencies

To use ContentEncoding, add the ktor-client-encoding artifact to your build script:

implementation("io.ktor:ktor-client-encoding:$ktor_version")

implementation "io.ktor:ktor-client-encoding:$ktor_version"

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-client-encoding-jvm</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

You can learn more about artifacts required by the Ktor client from Adding client dependencies.

Install `ContentEncoding`

To install ContentEncoding, pass it to the install function inside a client configuration block:

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.compression.*
//...
val client = HttpClient(CIO) {
    install(ContentEncoding)
}

Configure `ContentEncoding`

Enable encoders

You can configure which encoders are supported and specify their quality values (used in the Accept-Encoding header).

The example below enables the deflate and gzip encoders with custom quality values:

        val client = HttpClient(CIO) {
            install(ContentEncoding) {
                deflate(1.0F)
                gzip(0.9F)
            }
        }

If necessary, you can implement the ContentEncoder interface to create a custom encoder and register it using the customEncoder() function.

Set the `mode` property

By default, ContentEncoding handles response decompression only. You can use the mode property to define how the plugin operates.

The available values are:

ContentEncodingConfig.Mode.DecompressResponse: Decompresses responses only. This is the default mode.
ContentEncodingConfig.Mode.CompressRequest: Enables request body compression only.
ContentEncodingConfig.Mode.All: Enables both response decompression and request compression.

Encode request body

To enable request compression, set the mode property and use the compress() function inside the HttpRequestBuilder block:

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.compression.*
//...
val client = HttpClient(CIO) {
    install(ContentEncoding) {
        mode = ContentEncodingConfig.Mode.CompressRequest
        gzip()
    }
}
client.post("/upload") {
    compress("gzip")
    setBody(someLongBody)
}

In this example:

mode = ContentEncodingConfig.Mode.CompressRequest enables request compression.
gzip() registers the gzip encoder.
compress("gzip") applies gzip compression to this specific request.
The Content-Encoding header is added automatically.

26 February 2026