Creating your first project in IntelliJ IDEA

1. Step-by-step creation of a new project

A project in IntelliJ IDEA is not just a folder with files, but an entire container in which the IDE stores everything related to your future program. A project contains:

• source code, files with the .kt extension;
• project settings, for example, which version of the Java Virtual Machine to use for running;
• external libraries;
• auxiliary files and resources.

Inside a project there is usually a folder src — this is the main place for your Kotlin files. Everything that is not related to code is stored separately and does not get in the way.

Launching IntelliJ IDEA

On the start screen, click the big blue button New Project. If another project is already open, click File-New Project

Configuring project parameters

Pay attention to the left menu of the window: the language Kotlin must be selected there; by default it is set to Java. Now let’s go through the main fields:

• Name: the name of your project. This name will also be used to create a folder on disk. You can keep untitled1 or write another one, for example MyFirstProject.
• Location: the path where the project will be stored on your computer. By default, IDEA suggests its own IdeaProjects folder. Leave it as is.
• Create Git repository: lets you initialize Git version control right away. At this stage, to keep things simple, leave this checkbox unchecked.
• Build system: a build system is a tool that automates the code compilation process:
  • IntelliJ: the built-in, simplest build system in IDEA. Our choice to start.
  • Gradle: a powerful build system, the de-facto standard in the Kotlin world. But for learning right now it’s overkill. Using it now is like hammering nails with a microscope.
• Add sample code: IDEA will automatically create a basic file for us with the main function and a code example.
• Use compact project structure: keeps the folder structure simple and flat, without excessive nesting.

Installing a JDK from IntelliJ IDEA

If the JDK list is empty, our task is to download it right from here.

1. Click the drop-down list and select Download JDK...

2. A small window will open:

• Version: choose the Java version. Our course works great with modern LTS versions; choose 25.
• Vendor: the distribution vendor. As agreed, choose Amazon Corretto, but you can use another one as well.
• Location: the path where IDEA will download and install this JDK. Leave it as default.

3. Click the Select button or Download.

All settings are done. Click Create.

IntelliJ IDEA will start downloading the selected JDK, then create the project structure and open the main editor window. At the bottom of the screen you may see Indexing... — the IDE is reading files to provide you with hints. Just wait a minute.

On the first launch on Windows, you may see a notification: "Microsoft Defender may affect IDE performance". Feel free to click Automatically or Exclude folders. IDEA will add the project folder to antivirus exclusions so that code builds run fast.

Ultimate trial period

When you open the editor for the first time, you may see a large window or banner: "Your free Ultimate subscription trial is active".

Don’t worry, you don’t need to pay anything. The new unified IDEA version gives you access to all features for 30 days. For our course, the free capabilities are more than enough, so you can simply close this window.

2. Quick overview and first code

In IntelliJ IDEA, you can quickly change the scale of the entire interface without digging into settings: Alt + Shift + = or in Settings -- View -> Appearance -> Zoom IDE .

The code editor has opened with the Main.kt file.

1. Side menu

2. Project is the main window for navigating the project structure.

3. The currently opened file Main.kt

4. Buttons for Run ▶ (run) and Debug the program

IDEA generated an example code snippet for us with useful hints — TIPs. Let’s take a look at it:

Code walkthrough

The code looks a bit more complex than just “Hello World”, but it demonstrates the power of Kotlin really well:

• //TIPs ... — these are tips and shortcuts.
• val name = "Kotlin" — we created a variable name. Note that we didn’t have to write the variable type; Kotlin inferred it.
• println(...) — prints text to the screen.
• for (i in 1..5) — this is a loop. The code inside the curly braces will execute 5 times (for numbers from 1 to 5).
• println("i = $i") — Kotlin magic! The $ symbol lets you insert the value of the i variable right inside the string.

A red circle in the left gutter margin or an icon in the code is an entry point into debugging mode (debug). We’ll talk about it later. If you accidentally set such a point, just click it again to remove it.

Top-level functions

Just know it; you don’t need to dive into it right now.

Note: the main function is not wrapped in any class. In Kotlin, this is called a Top-Level Function. If a function doesn’t belong to a specific object, it can live directly in a .kt file.

Since the JVM requires classes, the Kotlin compiler will create an invisible class (usually MainKt) at runtime, so all technical requirements are met.

3. Project structure

Let’s take a closer look at the project structure on the left.

• .idea — a service folder of IntelliJ IDEA with project settings. You don’t need to edit it manually.
• src — the most important folder! Short for “sources”. This is where all your Kotlin code will live.
  • Main.kt — since we asked to add “sample code”, IDEA created this file. Inside it there is the fun main() function. This is the “entry point” — execution of any program starts from it.
• External Libraries — a virtual folder that displays connected libraries. Right now it contains our JDK and the standard Kotlin/JVM library.

4. Running the program

The best part is to run the code and see the result. Kotlin has a great and safe way to run a specific file.

Find the fun main() function in the code editor. To the left of it, in the line-number margin (the so-called gutter), there is a green triangle ▶. Click it and choose Run 'MainKt'.

At the bottom, the Run/Console window will open, and you will see the program output:

Let’s break down the output:

Launch command (the gray service line at the very beginning) is the path to the JVM that IDEA constructed to run your compiled code.

Program output (plain text) is the result of your println().

Exit code: Process finished with exit code 0. This is the final report. By convention, exit code 0 means the program successfully executed all instructions and finished without errors. Any other code means the program “crashed” during execution.

Also, after the first run, a hidden folder out will appear in the project. It contains compiled .class files — the Kotlin bytecode that the JVM executes.

What happens when you press Run?

1. Code compilation — the Kotlin compiler turns your .kt files into .class bytecode.
2. JVM startup — the Java Virtual Machine starts and looks for the entry point: fun main().
3. Execution — instructions run, and the result is printed to the console window.

5. Alt + Enter and hotkeys

While working in IntelliJ IDEA, you will notice gray hint text right in the editor: "Press Alt Enter... to see how IntelliJ IDEA suggests fixing it".

The Alt + Enter shortcut (or Option + Enter on macOS) is your main magic wand. If the IDE underlines code in red (error) or yellow (warning), place the cursor there and press these keys. IDEA will not only explain the problem, but also offer automatic fix options.

The IDE also supports many other shortcuts for navigation and debugging. You can see them in the JetBrains documentation or directly in the IDEA menu: Help -> Keyboard Shortcuts PDF.

6. Common mistakes and how to avoid them

The illusion of a “frozen program”

If you wrote the readln() function in your code, when you run it, no text will appear in the console — you will just see a blinking cursor. Beginners often think IDEA has frozen. In reality, the program is simply waiting for your input. Click inside the console window Run, type text, and press Enter.

The “wrong” main is running (Run Configurations)

If you create a second file Test.kt in the project and write another fun main() there, you will have two entry points. If you then press the big Run button at the very top of the window, IDEA may run the previous file. To always run exactly the code you are currently editing, click the green triangle ▶ to the left of the desired fun main() directly in the code editor.

Code is not in the src folder

The src folder is the source root. The IDE expects to find Kotlin code exactly there. If you create a .kt file outside this folder (for example, in the project root), the run button will not appear and the code will not compile.

Missing or incorrectly written fun main()
If you forget to write fun main() or you name the function fun myMain(), the program won’t start because the JVM won’t find the start point.

No JDK selected for the project
If you accidentally skipped the JDK step when creating the project, IDEA will show an error "Project SDK is not defined". This is easy to fix in settings: File → Project Structure → Project SDK.

Cyrillic and spaces in the project path
Although modern systems are more tolerant of names, the golden rule of a programmer is: project paths should not contain Russian letters, spaces, or special characters (for example, C:\My Projects\Project 1 is a bad idea). Use only Latin letters and underscores (C:\IdeaProjects\project_one).