July 05, 2025

KMP (Kotlin Multiplatform) Windows Quick Start

Kotlin Multiplatform Windows Quick Start

You have two main options for your project. The easiest and current recommended is the Android Studio plugin. You can also use the JetBrains Web Template, but that is a little more complex. Both methods work if upgrading to AGP 9 via the wizard. Your project will compile and run, but you do need to make some changes for the future. See the update section below.

Note: You can only compile iOS builds on an iOS machine. I believe you can get around this by compiling using Github Actions, but I have not tried this myself.

Updated 2026-02-03

When AGP 9.0.0 was first release, starting a new project in the current version of Android Studio Otter 3 and then updating led to a lot of problems!

A few days after that, they fixed something with the Android studio template / the upgrade procedure so your project will now build and run correctly.

PL Coding made a video about this before this fix was implemented but the changes he makes to teh project structure are still relevant.

I also wrote an upgrade guide for this - Migrating to AGP 9.0.0.

What did they change? I believe they either changed something with the web plugin template and/or the automated process for the gradle.properties (project properties). This can be seen in the my upgrade guide.

1) Kotlin Multiplatform Plugin (Recommended Solution)

It is recommended you installed the Kotlin Multiplatform Android Studio extension. This can be done via File->Settings>Plugins.

When starting a new project (after restarting your IDE), you should now have an option to make a Kotlin Multiplatform project.

Follow the wizard and select the platforms you need.

2) JetBrains Web Template Download

This has been testing with AGP 9.0.0 update (but I am unable to test iOS deployments). This method takes a while the first time you do it, but it is quite fast after that.

Purpose

Quickly set up your first Kotlin Multiplatform project in a Windows environment. This should take around five to ten minutes to follow (mainly due to dependency downloads and compile time), but may take longer if internet / machine is slow or if you get lost with the steps.

This will not show you how to write an app with any real functionality outside of a button and an animated image (which is a part of the template you download).

Prerequisites

Experience with Android Development
Android Studio Android Studio Giraffe | 2022.3.1 or above (tested with Narwhal | 2025.1.1 and 2025.1.2)

Notes

This is very easy if you are used to Android Studio. You need to download a project template as a start point, but then the dependency issues can be confusing to start.
You will not be able to build and iOS version of your app without suitable Apple hardware, but you can still make and work on the project.
There is no option to create a Kotlin Multiplatform project on Windows (or Linux) by default (but I believe this exists on Apple machines).

This guide - https://www.jetbrains.com/help/kotlin-multiplatform-dev/quickstart.html#ds3xqs_48 - is a good reference for Apple users - thank you, Stevekitkat (https://medium.com/@stevekitkat) for the reference

This guide shows you how to avoid having to set Java environment settings specifically for KMP
It also covers updating to the latest dependencies as of the date of writing that will build and run correctly (full list at end of guide)

Current Windows Options:

Full Process to Build and Run on Android and Desktop

Step 1 - Download Template (a minute or so):

Go to kmp.jetbrains.com to create your template project.

In New Project - Keep the default Project Name and Project ID for your first test
Below, make sure

Android is selected,
iOS->UI Implementation->Share UI (with Compose Multiplatform UI framework)
Desktop is selected
Web is NOT selected (currently Alpha so leave this for the first test)

Download the template

Step 2 - Extract and Copy (a few seconds):

Extract the project. You should end up with something like this in the extracted KotlinProject folder:

Copy (or move) the KotlinProject into your Android Studio Project Folder or perhaps a subfolder. Be sure you don't have an existing project with the same name first.

Step 3 - Open and Sync (around three minutes):

Open the project.

Select Trust Project (this code is coming from a reputable source, but of course, free free to open in preview mode first if you are worried).

This takes some time, but wait for the project to sync. This may take 30 seconds to a few minutes depending on your computer and internet connection.

It will look like this when it is syncing...

... and like this when it is finished (but you may need to complete step 4 first).

Step 4 - Set SDK / Java Settings (a few seconds to a few minutes):

IMPORTANT: Ensure your SDK location is set. Without this, you will get errors about not being able to find the correct Java version and to set your system settings correctly.

Open local.properties
Ensure your directory is set correctly

If it is blank, you can open an working Compose project and copy the location from there.
Example: sdk.dir=X\:\\Android\\SDK
Note the double backslashes (\\) between folder and the drive letter.

If you needed to change the SDK location, you should have to hit Sync Now for everything to work. This will take a bit of time to download all the required files.

Step 5 - Test Launch on Android (a minute or so):

Launch the project to make sure everything is working by hitting the Play Button.

Step 6 - Run on Desktop (a couple of minutes):

There are at least two ways to get it running on desktop:

Run in Terminal - enter -> ./gradlew :composeApp:desktopRun
Set up new configeration

From the top bar, click the three dots near the Run button
Select Edit
Select Add a New Configeration
Hit the Plus Nutton
Select Gradle
Change the Name to Desktop (or leave it the same if you wish)
Change the Run line to :composeApp:run
Click Ok
The newly added config should now be selected (select it if not)
Hit Run

Success!!!

Step 8 (Optional - Advanced) - Update Dependencies:

Update the following files if you want to run with all the latest improvements:
`Open gradle-wrapper-properties and update to latest version
As of writing, tested upgrading 8.9 to 8.14.3:
distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip
distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-bin.zip
Open libs.versions.toml and update to latest versions.
Updates - I manually updated these / used the upgrade assistant for the agp upgrade:
agp = "8.11.0" (or 8.12.0)
composeHotReload = "1.0.0-beta03" (or beta05)
android-targetSdk = "36"
android-compileSdk = "36"
Open build.gradle.kts (Modile :composeApp)
In android, Comment out the compilerOptions from androidTarget (not needed as this is set later in compileOptions anyway).
Also in android, Update the compileOptions to VERSION_21 (Java 21). This should give performance increases and other advantages. If you have any compatibility issues, you can also drop it back to version 11.

Of course, Sync and Run again to make sure it is working after the update.

Finished!

That should be everything you need to start working with KMP. In a Windows (or Linux?) environment, you should able to launch the Android and Desktop versions of the App. Coming soon is the Web based version (currently in Alpha).

Remember - you need Apple hardware (for Xcode) to build an iOS version, but you can still work on shared code on other machines.

Search This Blog

D9's Blog