Installation #

Before you can write a single line of Kotlin code, you need to set up the right development environment. The tools you choose will affect your daily productivity — from how fast you can debug, to how easily you can access documentation and auto-complete. This article covers four ways to install Kotlin: through IntelliJ IDEA as the recommended primary path, via the command line for those who prefer full control, through the VS Code plugin if you’re already comfortable with that editor, and Kotlin Playground for quick experiments without any setup.

Choosing the Right Installation Path #

Not every developer needs the same setup. Before you start installing, decide which path best fits your needs.

CHOOSE IntelliJ IDEA if:
  ✓ You're a full-time developer who'll work with Kotlin every day
  ✓ You're building Android apps or backends with Kotlin
  ✓ You want the full feature set: refactoring, visual debugger, profiler
  ✓ You're new to Kotlin and want immediate feedback from the IDE

CHOOSE Command Line if:
  ✓ You're in a server/CI environment without a GUI
  ✓ You want to integrate Kotlin into a custom build script
  ✓ You already have a favorite editor (Vim, Emacs) and only need a compiler
  ✓ You're a developer who wants to understand how the compiler works directly

CHOOSE VS Code if:
  ✓ You've invested heavily in VS Code configuration and don't want to switch
  ✓ You use Kotlin as one of many languages
  ✓ You're a frontend developer who touches Kotlin occasionally

CHOOSE Kotlin Playground if:
  ✗ Don't make this your primary setup for real projects
  ✓ You just want to try the syntax quickly without committing to anything
  ✓ You're following a tutorial and want to try the sample code

Installation via IntelliJ IDEA #

IntelliJ IDEA is the IDE developed directly by JetBrains — the company that also created Kotlin. As a result, Kotlin support in IntelliJ IDEA isn’t just an add-on plugin, but a first-class feature that’s continuously updated alongside the language’s evolution. Auto-complete, code inspection, quick-fixes, the debugger, and build tool integration all work without additional configuration.

Step 1 — Download IntelliJ IDEA #

Visit jetbrains.com/idea and choose the edition that fits:

For learning Kotlin and the majority of backend projects, the Community Edition is more than enough. Download the installer for your operating system.

Step 2 — Install IntelliJ IDEA #

Windows: Run the downloaded .exe file. Follow the installation wizard. Check the “Add launchers dir to the PATH” option so you can open IDEA from the terminal.

macOS: Open the .dmg file, drag IntelliJ IDEA to the Applications folder. On first launch, macOS may ask for confirmation because the app was downloaded from the internet — choose Open.

Linux: Extract the .tar.gz archive to a directory of your choice, then run the idea.sh script from the bin/ folder:

tar -xzf ideaIC-*.tar.gz -C /opt/
cd /opt/idea-IC-*/bin/
./idea.sh

On Linux, you can create a desktop entry so IntelliJ IDEA appears in the application launcher. Open IDEA and go to Tools → Create Desktop Entry.

Step 3 — Create Your First Kotlin Project #

Once IntelliJ IDEA is open:

1. Click New Project on the welcome screen.
2. Choose Kotlin from the language list in the left sidebar.
3. Decide the target type:

Available targets:
  • JVM            → desktop apps, backend, libraries
  • JavaScript     → frontend or full-stack with Kotlin/JS
  • Multiplatform  → one codebase for JVM, JS, and Native

4. Choose the build system: Gradle (recommended) or Maven.
5. Name the project and choose a directory location.
6. Click Create.

IntelliJ IDEA will create the complete project structure automatically — including the build.gradle.kts file (or pom.xml for Maven), the src/main/kotlin directory, and Kotlin configuration.

Step 4 — Write and Run Code #

Create a new file inside src/main/kotlin/ by right-clicking → New → Kotlin File/Class. Write your first code:

fun main() {
    println("Hello, Kotlin!")
    
    val name = "Developer"
    val message = "Welcome, $name!"
    println(message)
}

Click the green ▶ button next to the main function, or press Shift+F10 (Windows/Linux) / Ctrl+R (macOS). The output appears in the Run panel at the bottom of the IDE:

Hello, Kotlin!
Welcome, Developer!

IntelliJ IDEA bundles the Kotlin compiler — you don’t need to install Kotlin separately if you’re using IntelliJ IDEA.

Installation via Command Line #

If you work on servers, CI/CD pipelines, or prefer a terminal-based workflow, you can install the Kotlin Compiler directly without an IDE. There are two approaches: using SDKMAN! (for UNIX-based systems) or Homebrew (macOS only).

Using SDKMAN! (Linux & macOS) #

SDKMAN! is a version manager for various SDKs — similar to nvm for Node.js or pyenv for Python. It’s the recommended approach because you can easily switch between Kotlin versions.

Install SDKMAN!:

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

Close and reopen the terminal, then verify SDKMAN! is active:

sdk version
# Output: SDKMAN x.y.z

Install Kotlin:

sdk install kotlin

SDKMAN! will download the latest stable version automatically. To install a specific version:

sdk list kotlin          # see all available versions
sdk install kotlin 2.0.0 # install a specific version
sdk use kotlin 2.0.0     # use a specific version in this session
sdk default kotlin 2.0.0 # set as permanent default

Using Homebrew (macOS) #

brew update
brew install kotlin

Using Scoop (Windows) #

scoop install kotlin

Verifying the Installation #

Once the installation is complete, make sure everything works correctly:

kotlin -version
# Output: Kotlin version 2.x.x-release-xxx (JRE x.x.x)

kotlinc -version
# Output: kotlinc-jvm x.x.x (JRE x.x.x)

You’ll see two binaries installed:

Command Line Workflow #

Create a hello.kt file:

fun main() {
    println("Hello from the command line!")
    
    val args = arrayOf("one", "two", "three")
    args.forEachIndexed { index, value ->
        println("Argument $index: $value")
    }
}

Compile to JAR:

kotlinc hello.kt -include-runtime -d hello.jar

Flag explanations:

• -include-runtime — includes the Kotlin runtime in the JAR, so the JAR can run directly without Kotlin installed on the target machine
• -d hello.jar — the output file name

Run the JAR:

java -jar hello.jar

Output:

Hello from the command line!
Argument 0: one
Argument 1: two
Argument 2: three

Alternative: run directly without a JAR (for scripting):

kotlin hello.kt

Running Kotlin directly with kotlin hello.kt is slower because every execution recompiles from scratch. For production or frequently-run scripts, always compile to a JAR first.

Using the Kotlin REPL #

Kotlin provides a REPL (Read-Eval-Print Loop) — an interactive mode where you can type code and immediately get results, line by line. It’s useful for quick experiments or syntax checks.

kotlinc

Once inside the REPL:

Welcome to Kotlin version x.x.x (JRE x.x.x)
Type :help for help, :quit for quit
>>> 

>>> val x = 10
>>> val y = 20
>>> println(x + y)
30
>>> "Kotlin".uppercase()
res2: kotlin.String = KOTLIN
>>> :quit

Installation via the VS Code Plugin #

VS Code isn’t the primary IDE for Kotlin — its features are far below IntelliJ IDEA in terms of language support. But if you’ve invested heavily in VS Code configuration and only use Kotlin as part of your work, this setup can be a reasonable compromise.

Prerequisites #

The Kotlin plugin for VS Code depends on the Kotlin Language Server, which requires the Kotlin Compiler installed on your system. Make sure you’ve completed the command line installation from the previous section.

Verify:

which kotlinc
# /home/user/.sdkman/candidates/kotlin/current/bin/kotlinc

Install the Plugin #

1. Open VS Code.
2. Open the Extensions panel: Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (macOS).
3. Search for “Kotlin” and install the plugin from JetBrains.
4. Restart VS Code after installation.

Configuration #

If the compiler isn’t detected automatically, add the path to settings.json:

{
    "kotlin.compiler.jvm.target": "17",
    "kotlin.languageServer.enabled": true
}

VS Code’s Limitations for Kotlin #

Before you choose this path, understand what VS Code can’t do for Kotlin:

AVAILABLE in VS Code:
  ✓ Syntax highlighting
  ✓ Basic auto-complete
  ✓ Inline errors (partial)
  ✓ Go to definition

NOT AVAILABLE in VS Code:
  ✗ Integrated visual debugger
  ✗ Automatic refactoring (rename, extract method, etc.)
  ✗ Advanced code inspection and quick-fixes
  ✗ Seamless Gradle/Maven integration
  ✗ Android development

Kotlin Playground — No Installation #

Kotlin Playground is a browser-based editor that lets you write and run Kotlin code directly without installing anything. It’s not a solution for developing real projects, but it’s very useful for exploration and learning.

Open play.kotlinlang.org in your browser.

The editor looks like a simple IDE: a code area on the left, output on the right, and a Run button to execute the code.

// Try it directly in Kotlin Playground
fun main() {
    val fruitList = listOf("Mangga", "Apel", "Jeruk", "Durian")
    
    println("Favorite fruits:")
    fruitList.forEachIndexed { index, fruit ->
        println("${index + 1}. $fruit")
    }
    
    val longFruits = fruitList.filter { it.length > 5 }
    println("\nFruits with names > 5 characters: $longFruits")
}

Click Run and the output appears immediately without any setup.

Playground also supports multiple files in one session, useful for trying concepts like classes and interfaces:

// File: Animal.kt
abstract class Animal(val name: String) {
    abstract fun makeSound(): String
    
    fun introduce() {
        println("Hi, I'm $name and I sound like: ${makeSound()}")
    }
}

// File: Main.kt
class Cat(name: String) : Animal(name) {
    override fun makeSound() = "Meow!"
}

class Dog(name: String) : Animal(name) {
    override fun makeSound() = "Woof!"
}

fun main() {
    val animals = listOf(Cat("Mimi"), Dog("Rex"), Cat("Cleo"))
    animals.forEach { it.introduce() }
}

Understanding the Kotlin Workflow #

Once the environment is set up, it’s important to understand how Kotlin code runs behind the scenes. Kotlin isn’t a language that’s executed directly — it’s compiled first.

flowchart TD
    A[.kt File\nKotlin Source Code] --> B[kotlinc\nKotlin Compiler]
    B --> C{Target Platform?}
    C -- JVM --> D[JVM Bytecode\n.class / .jar]
    C -- JavaScript --> E[JavaScript\n.js]
    C -- Native --> F[Native Binary\n.exe / .kexe]
    D --> G[Java Virtual Machine\nJVM]
    G --> H[Program Execution]
    E --> I[Browser / Node.js]
    F --> J[Direct Execution\nWithout JVM]

For most Kotlin developers — especially those building backend or Android apps — the target is the JVM. This means Kotlin code is compiled to the same bytecode as Java, and runs on the same JVM.

The important consequence: Kotlin and Java are 100% interoperable. You can call Java libraries from Kotlin code, and vice versa.

Kotlin and the JVM #

Because Kotlin targets the JVM, you need to make sure a Java Development Kit (JDK) is installed on your system. IntelliJ IDEA usually bundles a JDK, but for the command line you may need to install one yourself.

# Check whether a JDK is installed
java -version
# Output: openjdk version "17.0.x" ...

javac -version
# Output: javac 17.0.x

If it isn’t installed, use SDKMAN! to install a JDK too:

sdk install java 17.0.9-tem

Kotlin supports JVM targets from version 8 upwards, but it’s recommended to use at least JDK 11 or 17 (LTS versions).

Full Environment Verification #

Once all components are installed, do a thorough verification by creating a simple project and running it end to end.

Minimal project structure:

first-project/
  ├── src/
  │   └── main/
  │       └── kotlin/
  │           └── Main.kt
  └── build.gradle.kts

build.gradle.kts file:

plugins {
    kotlin("jvm") version "2.0.0"
    application
}

repositories {
    mavenCentral()
}

application {
    mainClass.set("MainKt")
}

Main.kt file:

data class Student(
    val name: String,
    val id: String,
    val gpa: Double
)

fun main() {
    val students = listOf(
        Student("Budi Santoso", "2021001", 3.85),
        Student("Sari Dewi", "2021002", 3.92),
        Student("Ahmad Fauzi", "2021003", 3.71)
    )
    
    println("=== Outstanding Students ===")
    
    val topStudents = students
        .filter { it.gpa >= 3.75 }
        .sortedByDescending { it.gpa }
    
    topStudents.forEachIndexed { index, student ->
        println("${index + 1}. ${student.name} (${student.id}) — GPA: ${student.gpa}")
    }
    
    val average = students.map { it.gpa }.average()
    println("\nAverage GPA: %.2f".format(average))
}

Run with Gradle:

./gradlew run

Expected output:

=== Outstanding Students ===
1. Sari Dewi (2021002) — GPA: 3.92
2. Budi Santoso (2021001) — GPA: 3.85

Average GPA: 3.83

If this output appears, your Kotlin environment is fully ready.

Troubleshooting Common Issues #

Several problems commonly appear during the first setup. Learn to recognize the symptoms and their solutions.

kotlinc: command not found #

Happens when the PATH isn’t configured correctly after installation.

# ANTI-PATTERN: panic and reinstall immediately
# CORRECT: check the PATH first

echo $PATH
# Make sure there's a path to the SDKMAN or Kotlin bin directory

# If using SDKMAN!, reload the configuration:
source "$HOME/.sdkman/bin/sdkman-init.sh"

# Verify the binary location:
which kotlinc

JAVA_HOME not found error #

# Check whether JAVA_HOME is set:
echo $JAVA_HOME

# If empty, set it manually (adjust the path to your installation):
export JAVA_HOME=$(sdk home java current)  # if using SDKMAN!
export PATH="$JAVA_HOME/bin:$PATH"

# Add to ~/.bashrc or ~/.zshrc to make it permanent
echo 'export JAVA_HOME=$(sdk home java current)' >> ~/.bashrc

IntelliJ IDEA Doesn’t Recognize Kotlin #

If a Kotlin project isn’t highlighted correctly in IntelliJ IDEA:

1. File → Invalidate Caches → Invalidate and Restart
2. After restart: right-click the src/main/kotlin folder
   → Mark Directory As → Sources Root
3. Check: File → Project Structure → Modules
   → make sure there's a Kotlin Facet

Gradle Build Fails with a Kotlin Version Error #

// ANTI-PATTERN: inconsistent Kotlin versions between build files
// build.gradle.kts (root)
plugins {
    kotlin("jvm") version "1.9.0"
}

// submodule/build.gradle.kts — different version!
plugins {
    kotlin("jvm") version "2.0.0" // ✗ conflict!
}

// CORRECT: use a version catalog or define it at the root only
// gradle/libs.versions.toml
[versions]
kotlin = "2.0.0"

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }

Summary #

• IntelliJ IDEA is the primary choice — bundled Kotlin support with no extra configuration, a full feature set for professional development, and direct integration with the JetBrains toolchain.
• SDKMAN! for Kotlin management on the command line — enables multi-version installation and easy switching between versions, ideally paired with a JDK also managed by SDKMAN!.
• Kotlin compiles to JVM bytecode — meaning full interoperability with Java, running on the same JVM, and all Java ecosystem libraries can be used directly.
• The JDK is a prerequisite — make sure JDK 11 or 17 is installed before installing Kotlin, because the Kotlin compiler itself runs on the JVM.
• Kotlin Playground for experiments — use play.kotlinlang.org to try code quickly without any setup, not for real projects.
• VS Code can be used but is limited — debugging and refactoring features aren’t as good as IntelliJ IDEA; consider it only if you’ve already invested in VS Code configuration.
• Verify with a real project — don’t just verify the version with kotlin -version, but try compiling and running a program that uses basic Kotlin features to make sure the whole toolchain works.

← Previous: Home   Next: Main Syntax →