Server plugins

A typical request/response pipeline in Ktor looks like the following:

A request is received by the server and processed through the request pipeline. Ktor routes the request to the appropriate handler, where your application logic processes it. The response then passes through the response pipeline before being sent to the client.

Add functionality with plugins

Many applications require functionality that is separate from the application logic. This includes authentication, serialization and content encoding, compression, headers, cookies, and more. In Ktor, this functionality is provided by plugins.

Plugins can intercept different stages of request and response processing. They can therefore be applied at different points in the request/response pipeline:

The exact stage at which a plugin runs depends on the plugin and the hooks or pipeline phases it uses. In general, a request can be processed as follows:

The routing mechanism determines which handler should process the request.
Before being handed off to the handler, the request is processed by one or more plugins.
The handler uses the application logic to generate a response.
Before the response is sent to the client, the response is processed by one or more plugins.

Routing is a plugin

Plugins are designed to provide maximum flexibility, and to be present in any segment of the request/response pipeline. In Ktor, routing is itself implemented as a plugin:

Add a plugin dependency

Most plugins require a separate dependency. For example, the CORS plugin requires the ktor-server-cors artifact in the build script:

implementation(ktorLibs.server.cors)

implementation ktorLibs.server.cors

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

Install plugins

Plugins are generally configured during the initialization phase of the server using the install() function. Depending on how you create a server, you can install a plugin inside the embeddedServer() function or in an application module:

import io.ktor.server.application.*
import io.ktor.server.plugins.cors.*
import io.ktor.server.plugins.compression.*
// ...
fun main() {
    embeddedServer(Netty, port = 8080) {
        install(CORS)
        install(Compression)
        // ...
    }.start(wait = true)
}

import io.ktor.server.application.*
import io.ktor.server.plugins.cors.*
import io.ktor.server.plugins.compression.*
// ...
fun Application.module() {
    install(CORS)
    install(Compression)
    // ...
}

You can configure a plugin when you install it by passing a configuration block to the install() function.

For instance, when installing Sessions plugin, you can configure a cookie-based session by specifying the session type and cookie name:

install(Sessions) {
    cookie<MyCookie>("MY_COOKIE")
} 

Install plugins to specific routes

In Ktor, you can install plugins not only globally, but also on specific routes. This is useful when different resources require different plugin configurations.

For example, the following code shows installs the CachingHeader plugin on the /index route and configures it to add caching headers:

        route("/index") {
            install(CachingHeaders) {
                options { call, content -> CachingOptions(CacheControl.MaxAge(maxAgeSeconds = 1800)) }
            }
            get {
                call.respondText("Index page")
            }
        }

When the same plugin is installed at multiple levels, Ktor applies the following rules:

Configuration of a plugin installed to a specific route overrides the corresponding global plugin configuration.
If the same route is defined multiple times and contains multiple installations of the same plugin, routing merges the installations for that route. The last installation takes precedence.

In the following example both calls to /index/a and /index/b are handled by the second CachingHeaders installation only:

routing {
    route("index") {
        install(CachingHeaders) { /* First configuration */ }
        get("a") {
            // ...
        }
    }
    route("index") {
        install(CachingHeaders) { /* Second configuration */ }
        get("b") {
            // ...
        }
    }
}

Default, available, and custom plugins

Ktor does not install application plugins by default. Install the plugins that provide the functionality required by your application.

Ktor provides a wide range of plugins. You can find a complete list of the available plugins in the Ktor Project Generator.

You can also create your own custom plugins to encapsulate functionality that can be reused across your application or shared with other applications.

30 October 2026