Engines

Supported platforms

The table below lists platforms supported by each engine:

Supported Android/Java versions

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

* 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:

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.

• The XML serializer is supported on JVM only.

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.

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.

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")

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

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

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)

   import io.ktor.client.* import io.ktor.client.engine.apache.* val client = HttpClient(Apache)

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 } } }

   import io.ktor.client.* import io.ktor.client.engine.apache.* import org.apache.http.HttpHost val client = HttpClient(Apache) { engine { // this: [[[ApacheEngineConfig|https://api.ktor.io/ktor-client/ktor-client-apache/io.ktor.client.engine.apache/-apache-engine-config/index.html]]] followRedirects = true socketTimeout = 10_000 connectTimeout = 10_000 connectionRequestTimeout = 20_000 customizeClient { // this: HttpAsyncClientBuilder setProxy(HttpHost("127.0.0.1", 8080)) setMaxConnTotal(1000) setMaxConnPerRoute(100) // ... } 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")

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

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

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|https://api.ktor.io/ktor-client/ktor-client-java/io.ktor.client.engine.java/-java-http-config/index.html]]] 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 dependency:

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

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

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

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

   import io.ktor.client.* import io.ktor.client.engine.jetty.* 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.* import org.eclipse.jetty.util.ssl.SslContextFactory val client = HttpClient(Jetty) { engine { // this: [[[JettyEngineConfig|https://api.ktor.io/ktor-client/ktor-client-jetty/io.ktor.client.engine.jetty/-jetty-engine-config/index.html]]] sslContextFactory = SslContextFactory.Client() clientCacheSize = 12 } }

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")

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

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

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|https://api.ktor.io/ktor-client/ktor-client-android/io.ktor.client.engine.android/-android-engine-config/index.html]]] 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")

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

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

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|https://api.ktor.io/ktor-client/ktor-client-okhttp/io.ktor.client.engine.okhttp/-ok-http-config/index.html]]] config { // this: OkHttpClient.Builder followRedirects(true) // ... } addInterceptor(interceptor) addNetworkInterceptor(interceptor) preconfigured = okHttpClientInstance } }

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")

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

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

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")

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

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

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.

   sudo apt-get install libcurl4-gnutls-dev

2. Add the ktor-client-curl dependency:

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

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

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

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.

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")

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

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

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|https://api.ktor.io/ktor-client/ktor-client-cio/io.ktor.client.engine.cio/-c-i-o-engine-config/index.html]]] maxConnectionsCount = 1000 endpoint { // this: [[[EndpointConfig|https://api.ktor.io/ktor-client/ktor-client-cio/io.ktor.client.engine.cio/-endpoint-config/index.html]]] maxConnectionsPerRoute = 100 pipelineMaxSize = 20 keepAliveTime = 5000 connectTimeout = 5000 connectAttempts = 5 } https { // this: [[[TLSConfigBuilder|https://api.ktor.io/ktor-network/ktor-network-tls/io.ktor.network.tls/-t-l-s-config-builder/index.html]]] serverName = "api.ktor.io" cipherSuites = CIOCipherSuites.SupportedSuites trustManager = myCustomTrustManager random = mySecureRandom addKeyStore(myKeyStore, myKeyStorePassword) } } }