# Setup And Overview

> For the complete documentation index, see [llms.txt](https://kotlin.github.io/dataframe/llms.txt).

> **Tip:**
> Now available in Gradle (IDEA 2025.2+), Maven (IDEA 2025.3+), and Kotlin Toolchain (0.12.0+, IDEA 2026.2.1+) projects!

Kotlin DataFrame Compiler Plugin is a Kotlin compiler plugin that automatically generates

[type-safe extension properties](extensionpropertiesapi.html) for your dataframes,

allowing you to access columns and row values in a type-safe way and avoid mistakes in column names.

## Why use it?

* Access columns as regular properties: `df.name` instead of `df["name"]`.

* Get full IDE and compiler support: autocompletion, refactoring, and type checking.

* Improve code readability and safety when working with DataFrame.

Check out this video that shows how expressions update the schema of a dataframe:

[Video](images/compiler_plugin.mp4)

## Setup

We recommend using an up-to-date IntelliJ IDEA and Kotlin version for the best experience. Requires at least versions 2025.2 and 2.2.20, respectively.

Gradle:

Set up the plugins in `build.gradle.kts`:

```KOTLIN
kotlin("jvm") version "2.4.21"
```

```KOTLIN
kotlin("plugin.dataframe") version "2.4.21"
```

Setup library dependency:

```KOTLIN
implementation("org.jetbrains.kotlinx:dataframe:1.0.0-rc02")
```

If you're using a version older than Kotlin 2.4.0, incremental compilation must be disabled due to [this issue](https://youtrack.jetbrains.com/issue/KT-66735).

Add the following line to your `gradle.properties` file:

```PROPERTIES
kotlin.incremental=false
```

Sync the project. This is not needed anymore from Kotlin 2.4.0+.

See [Setup Kotlin DataFrame in Gradle](setupgradle.html) and [Custom Gradle Configuration](setupcustomgradle.html) for more details.

Maven:

The DataFrame compiler plugin can be used in Maven projects starting from IntelliJ IDEA 2025.3, available now as EAP builds

Update the `<kotlin-maven-plugin>` in the `<plugin>` section of your `pom.xml`:

```XML
<plugin>
    <artifactId>kotlin-maven-plugin</artifactId>
    <groupId>org.jetbrains.kotlin</groupId>
    <version>2.4.21</version>

    <configuration>
        <!-- Specify the Kotlin-dataframe plugin -->
        <compilerPlugins>
            <plugin>kotlin-dataframe</plugin>
        </compilerPlugins>
    </configuration>

    <!-- Add the Kotlin-dataframe plugin dependency -->
    <dependencies>
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-dataframe</artifactId>
            <version>2.4.21</version>
        </dependency>
    </dependencies>
</plugin>
```

Setup library dependency:

```XML
<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>dataframe</artifactId>
    <version>1.0.0-rc02</version>
</dependency>
```

Sync the project.

See [Setup Kotlin DataFrame in Maven](setupmaven.html) for more details.

Kotlin Toolchain:

The DataFrame compiler plugin can be used with [Kotlin Toolchain](https://kotlin-toolchain.org/) starting from Kotlin Toolchain 0.12.0+ and IntelliJ IDEA 2026.2.1+.

Update the `settings:` block in your `module.yaml` file as follows:

```YAML
settings:
  kotlin:
    version: 2.4.21
    dataframe: enabled
```

Doing so will enable the compiler plugin matching the Kotlin version. It will also automatically add the latest (`1.0.0-rc02`) [dataframe-core](modules.html#dataframe-core) dependency to your project.

In contrast to Maven and Gradle projects, this does NOT include any IO dependencies.

See [Setup Kotlin DataFrame in Kotlin Toolchain](setupkotlintoolchain.html) for more details about this.

If you want a specific version of the DataFrame library, you can do that in the `settings.kotlin.dataframe:` block:

```YAML
settings:
  kotlin:
    version: 2.4.21
    dataframe:
      enabled: true
      version: 1.0.0-rc02
```

## Features overview

### Static interpretation of DataFrame API

The plugin evaluates dataframe operations, given compile-time known arguments such as constant String, resolved types, property access calls. It updates the return type of the function call to provide properties that match column names and types. The goal is to reflect the result of the operations you apply to a dataframe in types and have a convenient typed API:

```KOTLIN
val weatherData = dataFrameOf(
    "time" to columnOf(0, 1, 2, 4, 5, 7, 8, 9),
    "temperature" to columnOf(12.0, 14.2, 15.1, 15.9, 17.9, 15.6, 14.2, 24.3),
    "humidity" to columnOf(0.5, 0.32, 0.11, 0.89, 0.68, 0.57, 0.56, 0.5)
)

weatherData.filter { temperature > 15.0 }.print()
```

The schema of DataFrame, as the compiler plugin sees it, is displayed when you hover on an expression or variable:

![image.png](images/schema_info.png)

### @DataSchema declarations

An untyped DataFrame can be assigned a data schema — a top-level interface or data class that describes the names and types of the columns in the dataframe.

```KOTLIN
@DataSchema
data class Repositories(
    @ColumnName("full_name")
    val fullName: String,
    @ColumnName("html_url")
    val htmlUrl: java.net.URL,
    @ColumnName("stargazers_count")
    val stargazersCount: Int,
    val topics: String,
    val watchers: Int
)

fun main() {
    val df = DataFrame
        .readCsv("https://raw.githubusercontent.com/Kotlin/dataframe/master/data/jetbrains_repositories.csv")
        .convertTo<Repositories>()

    df.filter { stargazersCount > 50 }.print()
}
```

[Learn more](dataschema.html) about data schema declarations

## Examples

* [Kotlin DataFrame in the IntelliJ IDEA Gradle project example](https://github.com/Kotlin/dataframe/blob/master/examples/projects/kotlin-dataframe-plugin-gradle-example) — an IntelliJ IDEA Gradle project showcasing simple DataFrame expressions using the Compiler Plugin.

* [Kotlin DataFrame in the IntelliJ IDEA Maven project example](https://github.com/Kotlin/dataframe/blob/master/examples/projects/kotlin-dataframe-plugin-maven-example) — an IntelliJ IDEA Maven project showcasing simple DataFrame expressions using the Compiler Plugin.

* [Kotlin DataFrame in the IntelliJ IDEA Kotlin Toolchain project example](https://github.com/Kotlin/dataframe/blob/master/examples/projects/kotlin-dataframe-plugin-kotlin-toolchain-example) — an IntelliJ IDEA Kotlin Toolchain project showcasing simple DataFrame expressions using the Compiler Plugin.

* [Compiler Plugin Examples](compilerpluginexamples.html) — a few examples of Compiler Plugin usage.