IntelliJ IDEA Setup Guide for Java Developers

IntelliJ IDEA is the de facto standard IDE for professional Java development. It offers intelligent code completion, deep static analysis, robust debugging, and seamless integration with build tools and version control—everything you need to write, test, and refactor production‑grade Java code efficiently.

This guide walks you through a professional‑grade setup: installing IntelliJ IDEA, connecting it to your JDK, configuring Maven or Gradle, and leveraging the features that make IntelliJ indispensable for Java engineers. By the end, your IDE will be ready for the entire JavaDevPro learning path.

1. Before You Begin

Verify that you have completed these prerequisites:

• A Java JDK installed (preferably JDK 17 or 21).
• JAVA_HOME environment variable set correctly.
• Basic familiarity with the terminal or command prompt.

If you need help installing the JDK, refer to the Install Java JDK guide before proceeding.

2. Choose an Edition

IntelliJ IDEA comes in two editions:

Edition	Key Features	Best For
Community	Core Java development, Maven/Gradle, Git, basic debugging	Beginners, open‑source projects, learning
Ultimate	Jakarta EE, Spring Boot, database tools, JavaScript, profiling, and more	Professional enterprise development

Recommendation: Start with the free Community Edition. It covers every topic in JavaDevPro. Upgrade to Ultimate when you need framework‑specific tooling for large Spring Boot or Jakarta EE projects.

3. Install IntelliJ IDEA

Windows

1. Download the .exe installer from jetbrains.com.
2. Run the installer. Accept the license.
3. Choose Create Desktop Shortcut (recommended) and associate .java files.
4. Complete the installation and launch IntelliJ IDEA.

macOS

1. Download the .dmg disk image.
2. Drag IntelliJ IDEA into the Applications folder.
3. On first launch, macOS may ask for confirmation—click Open.

Linux

JetBrains recommends the Toolbox App for automatic updates:

tar -xzf jetbrains-toolbox-*.tar.gz
./jetbrains-toolbox

Then install IntelliJ IDEA from within the Toolbox. Alternatively, you can use the snap package:

sudo snap install intellij-idea-community --classic

Launch IntelliJ IDEA after installation.

4. Configure the JDK

IntelliJ IDEA needs to know where your JDK lives. This is done once globally, and then inherited by every new project.

1. Open File → Project Structure (or press Ctrl+Alt+Shift+S / ⌘; on macOS).
2. Under Platform Settings → SDKs, click + → Add JDK.
3. Navigate to your JDK installation directory (e.g., /usr/lib/jvm/jdk-21 on Linux, C:\Program Files\Eclipse Adoptium\jdk-21... on Windows, or /Library/Java/JavaVirtualMachines/jdk-21.jdk on macOS).
4. Click OK. The JDK appears with its detected version and classpath.

You can also set a Global SDK so that new projects default to this JDK. Still in Project Structure, select Project and choose your JDK as the Project SDK.

Language level controls what Java features are available in the editor. It should match your SDK version (e.g., “21 – Records, pattern matching for switch”). IntelliJ sets this automatically when you choose a matching SDK.

5. Create Your First Java Project

1. Click New Project on the welcome screen, or go to File → New → Project.
2. Select Java on the left.
3. Choose your JDK from the Project SDK dropdown.
4. Keep the default template (“Add sample code” is fine for testing) and click Next.
5. Name your project (e.g., hello-javadevpro) and choose a location. Click Finish.

IntelliJ generates the project structure. Expand the src folder and open Main.java (if you selected the sample). Replace the contents with:

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, JavaDevPro!");
    }
}

• Run – click the green triangle in the gutter near main or press Ctrl+Shift+F10 (^⇧R on macOS).
• Rerun – use the run tool window or Shift+F10.
• Stop – click the red square in the run window or press Ctrl+F2.

IntelliJ compiles the code automatically and executes it. The Build tool window shows the output.

6. Understanding the IntelliJ Workspace

• Project tool window (Alt+1 / ⌘1) – navigate source files, packages, and external libraries.
• Editor – the main coding area. Tabs for open files.
• Terminal (Alt+F12 / ⌥F12) – a local terminal already pointed to your project directory.
• Maven / Gradle tool window – manage dependencies, run goals/tasks, and view the build lifecycle.
• Run / Debug configurations – dropdown in the toolbar; each run configuration defines what to execute.
• Problems / Inspection window – lists warnings and errors detected by static analysis.
• Structure view (Alt+7 / ⌘7) – shows methods and fields of the current class for quick navigation.

Spend a few minutes exploring these windows. Mastering the layout early saves hours of clicking later.

7. Configure Build Tools

Maven

• When you open a project containing pom.xml, IntelliJ automatically detects it and triggers dependency download.
• The Maven tool window shows Lifecycle, Plugins, and Dependencies.
• Use the Reload All Maven Projects button (circular arrows) if the IDE ever seems out of sync.
• To run a Maven goal, double‑click it in the Lifecycle list, or use Ctrl (twice) and type mvn clean install.

Gradle

• For Gradle projects, the Gradle tool window appears. IntelliJ uses the Gradle Wrapper (gradlew) automatically.
• Refresh dependencies with the Reload All Gradle Projects button.
• Tasks are grouped by project; double‑click a task to execute it.

When to choose Maven or Gradle: this guide does not prescribe one. Use Maven if your team prefers convention and XML, Gradle for Kotlin‑DSL and incremental builds. IntelliJ supports both equally well.

8. Debugging Java Applications

Debugging is an essential engineering skill. IntelliJ’s debugger lets you pause execution, inspect state, and step through logic.

1. Set a breakpoint by clicking in the gutter next to a line number. A red dot appears.
2. Run in debug mode – click the green bug icon or press Shift+F9.
3. When execution pauses, use the stepping controls:
   • Step Over (F8) – execute the current line and move to the next.
   • Step Into (F7) – enter the method being called.
   • Step Out (Shift+F8) – finish the current method and return to the caller.
4. Inspect Variables in the debug pane. Right‑click a variable and choose Evaluate Expression (Alt+F8) to run arbitrary code in the current context.
5. The Frames tab shows the call stack; click any frame to see its local variables.

Practice debugging a simple loop or method call. It builds intuition for diagnosing production issues later.

9. Recommended Plugins

Install only what you need. These plugins improve daily work without bloat:

Plugin	Purpose
Lombok	Annotation processing for @Data, @Builder, etc.
SonarLint	On‑the‑fly code quality checks (similar to SonarQube).
GitToolBox	Enhanced Git status, blame annotations, and inline feedback.
.ignore	Syntax highlighting and templates for .gitignore files.
Rainbow Brackets	Colorizes matching brackets, making nested code easier to read.

To install, go to File → Settings → Plugins (Ctrl+Alt+S / ⌘,), browse the Marketplace, and click Install. Restart the IDE if prompted.

10. Productivity Tips

Adopt these habits to work faster:

• Live Templates – type sout and press Tab for System.out.println(). View all templates in Settings → Editor → Live Templates.
• Code Completion – basic completion (Ctrl+Space) suggests method names and variables. Smart completion (Ctrl+Shift+Space) filters by type.
• Refactoring shortcuts – Shift+F6 renames anything safely across the project. Ctrl+Alt+Shift+T opens a menu of all refactorings.
• Navigation – Ctrl+N finds a class, Ctrl+Shift+N finds a file, Ctrl+Shift+Alt+N finds a symbol (method, field).
• Multi‑cursor – hold Alt (or ⌥ on macOS) and click to place additional cursors, or press Ctrl twice then arrow keys for column selection.
• Find Usages – Alt+F7 lists every usage of the selected symbol. Essential for understanding large codebases.
• Code Formatting – Ctrl+Alt+L formats the current file according to the project’s code style.

Configure a consistent code style under File → Settings → Editor → Code Style → Java. Import your team’s scheme or start from the default.

11. Common Problems

Symptom	Likely Cause	Solution
JDK not detected in new project	No global SDK set	File → Project Structure → SDKs and add your JDK.
Maven dependencies not downloading	Firewall or repository issue	Maven tool window → Reload. Check ~/.m2/settings.xml.
Gradle sync fails	Corrupted wrapper or network issue	Delete the .gradle folder and re‑sync.
Cannot run a class	Missing main method or wrong module config	Right‑click the file → Run. Verify the class has main.
Encoding issues (strange characters)	File encoding mismatch	File → File Encoding and set to UTF‑8 globally.
Language level mismatch	Project SDK does not match language level	File → Project Structure → Project and align them.
Build fails with compilation errors	Dependency conflicts or wrong JDK version	Inspect the Build tool window for the exact error.

Most issues can be resolved by re‑importing the project and checking the Problems tool window for IDE‑detected inconsistencies.

12. Best Practices

• Keep IntelliJ up to date – JetBrains releases regular performance and security fixes.
• Use an LTS JDK as the default, and add other JDKs for specific projects.
• Enable automatic imports (Settings → Editor → General → Auto Import). It keeps code tidy without manual effort.
• Integrate version control – Git is fully integrated. Commit, push, and review diffs without leaving the IDE.
• Limit plugins – only install tools that you actively use; many plugins degrade startup time and stability.
• Follow a code style – either the default or a team‑defined scheme, enforced by IDE settings and reformat on save if desired.
• Use inspections – the IDE flags potential bugs and style issues in real time. Address them as they appear.

13. Next Steps

Your IDE is now configured for professional Java development. Continue your journey with:

• Java Foundations – learn the language and core APIs.
• Java Learning Roadmap – see the full roadmap.
• Maven vs Gradle – choose the right build tool for your project.
• Java Language Fundamentals – start writing idiomatic Java code.

IntelliJ IDEA is the workshop where your Java engineering skills will be forged. Invest time mastering it, and you will ship better code faster.