Kotlin Academy · Lesson

kotlinx.serialization Setup

Add the plugin.

Lesson 1 of 413 steps

kotlinx.serialization Setup is a free Kotlin Academy lesson on CoddyKit. This is lesson 1 of 4. Any 3 lessons of this learning path are free to read in full — after that, CoddyKit PRO unlocks every lesson, plus hands-on practice with a built-in code editor and a 24/7 AI tutor. It is part of the Kotlin Academy learning path, and your progress syncs across the web and the CoddyKit app. The Kotlin Academy course includes 4 lessons in total.

What is kotlinx.serialization?

kotlinx.serialization is the official Kotlin library for converting objects to and from formats like JSON.

Pure Kotlin, multiplatform-ready
Compile-time code generation (no reflection)
Maintained by JetBrains

It works with a compiler plugin plus a runtime library.

Why a Compiler Plugin?

Unlike reflection-based libraries, kotlinx.serialization generates serializers at compile time.

Faster, no runtime reflection cost
Works on Kotlin/Native and JS where reflection is limited
Type-safe and verified by the compiler

This is why you must apply the kotlin-serialization plugin, not just add a dependency.

Applying the Plugin (Kotlin DSL)

In build.gradle.kts apply the serialization plugin with the same version as your Kotlin plugin.

plugins {
    kotlin("jvm") version "2.0.0"
    kotlin("plugin.serialization") version "2.0.0"
}

Adding the Runtime Dependency

The plugin generates code, but you also need the JSON runtime library.

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
}

Version Alignment Matters

The plugin.serialization version must match your Kotlin compiler version. The runtime library has its own independent version.

Plugin version = Kotlin version (e.g. 2.0.0)
Runtime version is separate (e.g. 1.7.1)

Mismatched plugin/Kotlin versions cause cryptic build errors.

Other Formats

JSON is the most common, but kotlinx.serialization supports more formats via extra artifacts:

kotlinx-serialization-json — JSON
kotlinx-serialization-cbor — CBOR binary
kotlinx-serialization-protobuf — Protocol Buffers

You add only the format artifacts you need.

Groovy DSL Equivalent

If your project uses Groovy build.gradle instead of Kotlin DSL, the setup looks like this.

// build.gradle (Groovy)
plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.0.0'
    id 'org.jetbrains.kotlin.plugin.serialization' version '2.0.0'
}

dependencies {
    implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1'
}

The Json Entry Point

Once set up, you use the Json object from kotlinx.serialization.json as your main entry point for encoding and decoding.

import kotlinx.serialization.json.Json

val format = Json
// format.encodeToString(...) / format.decodeFromString(...)

A Minimal Working Snippet

Here is the smallest end-to-end example once the plugin and runtime are configured.

import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json

@Serializable
data class City(val name: String, val population: Int)

fun main() {
    val city = City("Istanbul", 15000000)
    val json = Json.encodeToString(city)
    println(json)
}

Multiplatform Setup

In a Kotlin Multiplatform project, add the runtime to commonMain so all targets share it.

sourceSets {
    val commonMain by getting {
        dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
        }
    }
}

Common Setup Mistakes

Watch out for these frequent issues:

Forgetting the plugin — you get Serializer has not been found
Plugin version not matching Kotlin version
Adding the runtime but not the plugin (or vice versa)
Missing import of encodeToString

Quick Check

Why does kotlinx.serialization require a Gradle compiler plugin?

Answer it in the interactive lesson

Recap

You set up kotlinx.serialization by:

Applying the kotlin("plugin.serialization") plugin matching your Kotlin version
Adding the kotlinx-serialization-json runtime dependency
Using the Json object as the entry point

Next you'll annotate model classes with @Serializable.

Free to start

Learn Kotlin with an AI tutor — free

Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.

Courses: 51
Lessons: 203

Start learning free View the full course

Frequently Asked Questions

Is the “kotlinx.serialization Setup” lesson free?

Yes — any 3 lessons of the Kotlin Academy learning path, including “kotlinx.serialization Setup”, are free to read in full here on the web. After that, CoddyKit PRO unlocks every lesson, plus interactive practice with a built-in code editor and a 24/7 AI tutor. The Kotlin Academy course includes 4 lessons in total.

What will I learn in “kotlinx.serialization Setup”?

Add the plugin. You practise Kotlin Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Kotlin Academy?

No prior experience is required. Kotlin Academy on CoddyKit is structured for beginners through advanced learners, so you can start here or from the beginning and move at your own pace. This is lesson 1 of 4.

How long does the “kotlinx.serialization Setup” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Kotlin Academy lesson?

Yes. Every Kotlin Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Kotlin Academy