Client engines

Edit pageLast modified: 06 February 2025

The Ktor HTTP client can be used on different platforms, including JVM, Android, JavaScript, and Native. A specific platform may require a specific engine that processes network requests. For example, you can use Apache or Jettyfor JVM applications, OkHttp or Android for Android, Curl for desktop applications targeting Kotlin/Native, and so on. Different engines may have specific features and provide different configuration options.

Requirements and limitations

Supported platforms

The table below lists platforms supported by each engine:

Engine

Platforms

Apache

JVM

Java

JVM

Jetty

JVM

Android

JVM, Android

OkHttp

JVM, Android

Darwin

Native

WinHttp

Native

Curl

Native

CIO

JVM, Android, Native

Js

JavaScript

Supported Android/Java versions

Client engines targeting JVM or both JVM and Android support the following Android/Java versions:

Engine

Android version

Java version

Apache

8+

Java

11+

Jetty

11+

CIO

7.0+ *

8+

Android

1.x+

8+

OkHttp

5.0+

8+

* To use the CIO engine on older Android versions, you need to enable Java 8 API desugaring.

Limitations

The table below shows whether a specific engine supports HTTP/2 and WebSockets:

Engine

HTTP/2

WebSockets

Apache

✅️ (for Apache5)

✖️

Java

✅

✅️

Jetty

✅

✖️

CIO

✖️

✅

Android

✖️

✖️

OkHttp

✅

✅

Js

✅

✅

Darwin

✅

✅

WinHttp

✅

✅

Curl

✅

✖️

You also need to consider the following limitations that affect general client configuration and using of specific plugins:

  • If an engine supports HTTP/2, you can enable it by customizing the engine configuration (see an example for the Java engine).

  • To configure SSL in the Ktor client, you need to customize the configuration of a selected engine.

  • Some engines don't support proxy.

  • The Logging plugin provides different logger types for different platforms.

  • The HttpTimeout plugin has some limitations for specific engines.

Add an engine dependency

Apart from the ktor-client-core artifact, the Ktor client requires adding a specific dependency for each engine. For each of the supported platforms, you can see the available engines and required dependencies in a corresponding section:

tip

For different engines, Ktor provides platform-specific artifacts with suffixes such as -jvm or -js, for example, ktor-client-cio-jvm. Gradle resolves artifacts appropriate for a given platform while Maven doesn't support this capability. This means that for Maven, you need to add a platform-specific suffix manually.

Create a client with a specified engine

To create the HTTP client with a specific engine, pass an engine class as an argument to the HttpClient constructor. For example, you can create a client with the CIO engine as follows:

import io.ktor.client.*
import io.ktor.client.engine.cio.*

val client = HttpClient(CIO)

Default engine

If you call the HttpClient constructor without an argument, the client will choose an engine automatically depending on the artifacts added in a build script.

import io.ktor.client.*

val client = HttpClient()

This can be useful for multiplatform projects. For example, for a project targeting both Android and iOS, you can add the Android dependency to the androidMain source set and the Darwin dependency to the iosMain source set. The necessary dependency will be selected at compile time.

Configure an engine

You can configure an engine using the engine method. All engines share several common properties exposed by HttpClientEngineConfig, for example:

HttpClient() {
    engine {
        // this: HttpClientEngineConfig
        threadsCount = 4
        pipelining = true
    }
}

To learn how to configure a specific engine, see a corresponding section below.

JVM

In this section, we'll take a look at engines available for JVM.

Apache

The Apache engine supports HTTP/1.1 and provides multiple configuration options. You can also use the Apache5 engine if you need HTTP/2 support, which has HTTP/2 enabled by default.

  1. Add the ktor-client-apache5 or ktor-client-apache dependency:

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

  2. Pass the Apache5/Apache class as an argument to the HttpClient constructor:

    import io.ktor.client.*
import io.ktor.client.engine.apache5.*

val client = HttpClient(Apache5)

  3. To configure an engine, pass settings exposed by Apache5EngineConfig/ApacheEngineConfig to the engine method:

    import io.ktor.client.*
import io.ktor.client.engine.apache5.*
import org.apache.hc.core5.http.*

val client = HttpClient(Apache5) {
    engine {
        // this: Apache5EngineConfig
        followRedirects = true
        socketTimeout = 10_000
        connectTimeout = 10_000
        connectionRequestTimeout = 20_000
        customizeClient {
            // this: HttpAsyncClientBuilder
            setProxy(HttpHost("127.0.0.1", 8080))
            // ...
        }
        customizeRequest {
            // this: RequestConfig.Builder
        }
    }
}

Java

The Java engine uses the Java HTTP Client introduced in Java 11. To use it, follow the steps below:

  1. Add the ktor-client-java dependency:

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

  2. Pass the Java class as an argument to the HttpClient constructor:

    import io.ktor.client.*
import io.ktor.client.engine.java.*

val client = HttpClient(Java)

  3. To configure an engine, pass settings exposed by JavaHttpConfig to the engine method:

    import io.ktor.client.*
import io.ktor.client.engine.*
import io.ktor.client.engine.java.*

val client = HttpClient(Java) {
    engine {
        // this: JavaHttpConfig
        threadsCount = 8
        pipelining = true
        proxy = ProxyBuilder.http("http://proxy-server.com/")
        protocolVersion = java.net.http.HttpClient.Version.HTTP_2
    }
}

Jetty

The Jetty engine supports only HTTP/2 and can be configured in the following way:

  1. Add the ktor-client-jetty-jakarta dependency:

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

  2. Pass the Jetty class as an argument to the HttpClient constructor:

    import io.ktor.client.*
import io.ktor.client.engine.jetty.jakarta.*

val client = HttpClient(Jetty)

  3. To configure an engine, pass settings exposed by JettyEngineConfig to the engine method:

    import io.ktor.client.*
import io.ktor.client.engine.jetty.jakarta.*
import org.eclipse.jetty.util.ssl.SslContextFactory

val client = HttpClient(Jetty) {
    engine {
        // this: JettyEngineConfig
        sslContextFactory = SslContextFactory.Client()
        clientCacheSize = 12
    }
}

JVM and Android

In this section, we'll take a look at engines available for JVM/Android and their configurations.

Android

The Android engine targets Android and can be configured in the following way:

  1. Add the ktor-client-android dependency:

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

  2. Pass the Android class as an argument to the HttpClient constructor:

    import io.ktor.client.*
import io.ktor.client.engine.android.*

val client = HttpClient(Android)

  3. To configure an engine, pass settings exposed by AndroidEngineConfig to the engine method:

    import io.ktor.client.*
import io.ktor.client.engine.android.*
import java.net.Proxy
import java.net.InetSocketAddress

val client = HttpClient(Android) {
    engine {
        // this: AndroidEngineConfig
        connectTimeout = 100_000
        socketTimeout = 100_000
        proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("localhost", 8080))
    }
}

OkHttp

The OkHttp engine is based on OkHttp can be configured in the following way:

  1. Add the ktor-client-okhttp dependency:

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

  2. Pass the OkHttp class as an argument to the HttpClient constructor:

    import io.ktor.client.*
import io.ktor.client.engine.okhttp.*

val client = HttpClient(OkHttp)

  3. To configure an engine, pass settings exposed by OkHttpConfig to the engine method:

    import io.ktor.client.*
import io.ktor.client.engine.okhttp.*

val client = HttpClient(OkHttp) {
    engine {
        // this: OkHttpConfig
        config {
            // this: OkHttpClient.Builder
            followRedirects(true)
            // ...
        }
        addInterceptor(interceptor)
        addNetworkInterceptor(interceptor)

        preconfigured = okHttpClientInstance
    }
}

Native

In this section, we'll have a look at how to configure engines targeted for Kotlin/Native.

tip

Using Ktor in a Kotlin/Native project requires a new memory manager, which is enabled by default starting with Kotlin 1.7.20.

Darwin

The Darwin engine targets Darwin-based operating systems (such as macOS, iOS, tvOS, and so on) and uses NSURLSession under the hood. To use the Darwin engine, follow the steps below:

  1. Add the ktor-client-darwin dependency:

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

  2. Pass the Darwin class as an argument to the HttpClient constructor:

    import io.ktor.client.*
import io.ktor.client.engine.darwin.*

val client = HttpClient(Darwin)

  3. To configure an engine, pass settings exposed by DarwinClientEngineConfig to the engine function. For instance, you can use the configureRequest function to access NSMutableURLRequest or configureSession to customize a session configuration. The code snippet below shows how to use configureRequest:

    val client = HttpClient(Darwin) {
    engine {
        configureRequest {
            setAllowsCellularAccess(true)
        }
    }
}

    You can find the full example here: client-engine-darwin.

WinHttp

The WinHttp engine targets Windows-based operating systems. To use the WinHttp engine, follow the steps below:

  1. Add the ktor-client-winhttp dependency:

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

  2. Pass the WinHttp class as an argument to the HttpClient constructor:

    import io.ktor.client.*
import io.ktor.client.engine.winhttp.*

val client = HttpClient(WinHttp)

  3. To configure an engine, pass settings exposed by WinHttpClientEngineConfig to the engine function. For instance, you can use the protocolVersion property to change the HTTP version:

    val client = HttpClient(WinHttp) {
    engine {
        protocolVersion = HttpProtocolVersion.HTTP_1_1
    }
}

    You can find the full example here: client-engine-winhttp.

Curl

For desktop platforms, Ktor also provides the Curl engine. This engine is supported for the following platforms: linuxX64, macosX64, macosArm64, mingwX64. To use the Curl engine, follow the steps below:

  1. Install the libcurl library.

    tip

    On Linux, you have to install the gnutls version of libcurl. To install this version on Ubuntu you can run:

    sudo apt-get install libcurl4-gnutls-dev

    tip

    On Windows, you may want to consider the MinGW/MSYS2 curl binary.

  2. Add the ktor-client-curl dependency:

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

  3. Pass the Curl class as an argument to the HttpClient constructor:

    import io.ktor.client.*
import io.ktor.client.engine.curl.*

val client = HttpClient(Curl)

  4. To configure an engine, pass settings exposed by CurlClientEngineConfig to the engine method. The code snippet below shows how to disable SSL verification for testing purposes:

    val client = HttpClient(Curl) {
    engine {
        sslVerify = false
    }
}

    You can find the full example here: client-engine-curl.

JVM, Android, and Native

CIO

CIO is a fully asynchronous coroutine-based engine that can be used on JVM, Android, and Native platforms. It supports only HTTP/1.x for now. To use it, follow the steps below:

  1. Add the ktor-client-cio dependency:

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

  2. Pass the CIO class as an argument to the HttpClient constructor:

    import io.ktor.client.*
import io.ktor.client.engine.cio.*

val client = HttpClient(CIO)

  3. To configure an engine, pass settings exposed by CIOEngineConfig to the engine method:

    import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.network.tls.*

val client = HttpClient(CIO) {
    engine {
        // this: CIOEngineConfig
        maxConnectionsCount = 1000
        endpoint {
            // this: EndpointConfig
            maxConnectionsPerRoute = 100
            pipelineMaxSize = 20
            keepAliveTime = 5000
            connectTimeout = 5000
            connectAttempts = 5
        }
        https {
            // this: TLSConfigBuilder
            serverName = "api.ktor.io"
            cipherSuites = CIOCipherSuites.SupportedSuites
            trustManager = myCustomTrustManager
            random = mySecureRandom
            addKeyStore(myKeyStore, myKeyStorePassword)
        }
    }
}

JavaScript

The Js engine can be used for JavaScript projects. This engine uses the fetch API for browser applications and node-fetch for Node.js. To use it, follow the steps below:

  1. Add the ktor-client-js dependency:

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

  2. Pass the Js class as an argument to the HttpClient constructor:

    import io.ktor.client.*
import io.ktor.client.engine.js.*

val client = HttpClient(Js)

    You can also call the JsClient function to get the Js engine singleton:

    import io.ktor.client.engine.js.*

val client = JsClient()

You can find the full example here: client-engine-js.

Example: How to configure an engine in a multiplatform mobile project

To configure engine-specific options in a multiplatform mobile project, you can use expect/actual declarations. Let's demonstrate how to achieve this using a project created in the Creating a cross-platform mobile application tutorial:

  1. Open the shared/src/commonMain/kotlin/com/example/kmmktor/Platform.kt file and add a top-level httpClient function, which accepts a client configuration and returns HttpClient:

    expect fun httpClient(config: HttpClientConfig<*>.() -> Unit = {}): HttpClient

  2. Open shared/src/androidMain/kotlin/com/example/kmmktor/Platform.kt and add an actual declaration of the httpClient function for the Android module:

    import io.ktor.client.*
import io.ktor.client.engine.okhttp.*
import java.util.concurrent.TimeUnit

actual fun httpClient(config: HttpClientConfig<*>.() -> Unit) = HttpClient(OkHttp) {
   config(this)

   engine {
      config {
         retryOnConnectionFailure(true)
         connectTimeout(0, TimeUnit.SECONDS)
      }
   }
}

    This example shows how to configure the OkHttp engine, but you can also use other engines supported for Android.

  3. Open shared/src/iosMain/kotlin/com/example/kmmktor/Platform.kt and add an actual declaration of the httpClient function for the iOS module:

    import io.ktor.client.*
import io.ktor.client.engine.darwin.*

actual fun httpClient(config: HttpClientConfig<*>.() -> Unit) = HttpClient(Darwin) {
   config(this)
   engine {
      configureRequest {
         setAllowsCellularAccess(true)
      }
   }
}

  4. Finally, open shared/src/commonMain/kotlin/com/example/kmmktor/Greeting.kt and replace the HttpClient() constructor with the httpClient function call:

    private val client = httpClient()