How to setup the Java SDK and use JavaFX on macOS/Windows

Overview: Key Components & Their Roles

This guide covers setting up a JavaFX development environment. Here's a quick look at the essential parts and why they matter:

Environment Variables (JAVA_HOME, PATH): Tells your system where to find the Java Development Kit (JDK) for command-line tools.
Build Tool (Maven/Gradle): Manages project dependencies (like JavaFX libraries) and automates the build process.
FXML: XML-based files for defining the structure and layout of your user interface, separating design from logic.
SceneBuilder: A visual tool for designing and editing FXML files without writing XML code directly.

1: Set $JAVA_HOME (environment variable)

Set up JAVA_HOME globally on macOS and Windows to prepare your system for Java applications.

1.1: Download Java SDK

Download Java SDK:
- For macOS ARM64 (M1/M2/M3): Download the macOS ARM64 DMG Installer
- For macOS Intel: Download the macOS x64 DMG Installer
- For Windows: Download the Windows x64 Installer
OpenJDK Alternative: OpenJDK offers a free, open-source implementation of Java with identical functionality.
- For macOS, you can also install via Homebrew: brew install openjdk@21

Note on JDK version

I recommend always using the current long-term stable branch (LTS), which is 21 as of this writing. Additionally, a lot of conflicts can be most easily resolved with just one Java version installed on your system. If you already have multiple versions installed, see Section 6.2 on managing multiple Java versions.

1.2: Install Java

macOS: Open the downloaded .dmg file and follow the installer instructions. The default installation location will be: /Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home
Windows: Run the installer and follow the on-screen instructions. The default location is typically: C:\Program Files\Java\jdk-21

1.3: Set JAVA_HOME environment variable

macOS: Add JAVA_HOME to your .zshrc file and apply it immediately:

bash

`echo 'export JAVA_HOME=$(/usr/libexec/java_home)' >> ~/.zshrc && source ~/.zshrc`

Windows: Open System Properties (Win + Pause/Break), go to Advanced system settings, and under Environment Variables, add:
- Variable name: JAVA_HOME
- Variable value: C:\Program Files\Java\jdk-21 (update version if different)
- Then edit the Path variable and add %JAVA_HOME%\bin

Do you still need JAVA_HOME?

While modern IDEs often manage their own JDK settings, setting JAVA_HOME globally is still crucial for command-line tools like Maven and Gradle.

Part 2: Setting up Java & JavaFX in IntelliJ IDEA and VS Code

What is JavaFX?

JavaFX is a toolkit/library for developing graphical (GUI) applications in Java. It is no longer included with the JDK since Java 11. While you can still download it from Gluon JavaFX, it's best practice to let your build tool (Maven/Gradle) manage it as a project dependency. Avoid installing JavaFX system-wide.

Integrated Setup in IntelliJ IDEA and VS Code: Both IDEs offer seamless onboarding for JavaFX projects. Select JavaFX from the project templates, and the IDE will configure the necessary settings.

2.1: Setup for Microsoft VS Code

What is the Java extension pack?

The Extension Pack for Java is a great way to get Java setup in one click in VS Code with things like IntelliSense, debugging, and more.

Download Microsoft VS Code: Then install the Extension Pack for Java

2.2: Setup for IntelliJ IDEA

Download IntelliJ IDEA

IntelliJ IDEA - batteries included

After you download and install an IntelliJ IDE from JetBrains), you're all set! IDEA comes with what you need to get started with Java & JavaFX.

Version Compatibility is Key

Based on my experience, using the latest Long-Term Support (LTS) versions consistently across tools minimizes compatibility issues. I recommend sticking to JDK 21, JavaFX 21, and Scene Builder 23 (or the latest corresponding LTS versions) for a smoother setup. Using other versions on my ARM64-based Mac resulted in errors, so watch out for that.

Tip: Ensure your build configuration (pom.xml or build.gradle) also uses the same Java LTS version. See Section 6.4 for an example.

Part 3: Integrating Scene Builder

Scene Builder is a visual layout tool for designing JavaFX UIs (.fxml files). First, download it, then tell your IDE where to find it.

3.1: Download and Install Scene Builder

Visit the Gluon Scene Builder website to download the latest version (LTS recommended, currently 23). Install it using the downloaded installer.

3.2: Configure Path in IntelliJ IDEA

Go to Settings/Preferences > Languages & Frameworks > JavaFX.
Click the folder icon next to "Path to SceneBuilder" and navigate to the installed Scene Builder application.
- macOS typical path: /Applications/SceneBuilder.app > Contents > MacOS > SceneBuilder
- Windows typical path: C:\Program Files\SceneBuilder\SceneBuilder.exe (or similar)

Setting Scene Builder path in IntelliJ IDEA Preferences

Navigate to Languages & Frameworks > JavaFX in IntelliJ settings

Selecting Scene Builder application path in IntelliJ IDEA

Select the Scene Builder application executable path

3.3: Configure Path in VS Code

Install the SceneBuilder extension for Visual Studio Code.
Open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows)
Type Configure Scene Builder path and press enter
Browse to and select your installed Scene Builder executable

Setting Scene Builder path via Command Palette in VS Code

Use the Command Palette (Cmd/Ctrl+Shift+P) to set the SceneBuilder path in VS Code

Once configured, you can right-click an .fxml file in the VS Code explorer and choose "Open in Scene Builder". We'll cover how to create the project and open it in Scene Builder in the next step below.

Does Scene Builder require environment variables?

Scene Builder is self-contained and doesn't need JAVA_HOME. It edits .fxml files directly. You only need to configure the path within your IDE to enable direct opening of FXML files.

Part 4: Creating a JavaFX Project

Now that the JDK and Scene Builder are set up, here's how to create a new JavaFX project.

4.1: Create New Project in IntelliJ IDEA

Go to File > New > Project.
Select JavaFX from the list on the left.
Choose your project SDK (should be the Java 21 JDK you installed).
Select Maven or Gradle as the build system.
Fill in your project details (Name, Location, GroupId, ArtifactId).
Click Create.

Creating a new JavaFX project in IntelliJ IDEA

IntelliJ IDEA New Project wizard for JavaFX

4.2: Create New Project in VS Code

Open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows).
Type Java: Create Java Project and press Enter
Select JavaFX from the list
It'll ask for your desired repository version number for this new project, you can just hit enter to proceed with the default ('version' 1.0-SNAPSHOT)
When prompted to confirm (Y/N), make sure you hit N to be able to change the JavaFX version to 21 (no other details should need changed, just hit enter to proceed with the default each time)
Choose a folder location for your new project

VS Code command palette and prompts for creating a new JavaFX project

Use the Command Palette (Cmd/Ctrl+Shift+P) -> 'Java: Create Java Project' -> 'JavaFX' and follow the prompts

Once created, VS Code will open the new project. You can test run it:
- Open the App.java file (usually under src/main/java/com/example/).
- Click the "Run" button that appears above the main method or press F5.

VS Code showing the run button for App.java and the resulting JavaFX window

Run the default App.java to ensure the JavaFX project builds and displays the initial window

After the project is successfully created, VS Code will show a notification. Click Open to load the project in a new window.

VS Code notification showing successful project creation with an Open button

Click the 'Open' button in the notification to open your new JavaFX project

What are the components of a JavaFX application?

JavaFX separates layout (FXML) from logic (Java Controllers). Scene Builder edits the FXML files visually. The pom.xml (Maven) or build.gradle file manages dependencies like the JavaFX libraries. Key components include:

FXML Files (e.g., primary.fxml, secondary.fxml): XML files describing the GUI layout.
Java Controllers: Classes linked to FXML for handling logic and interaction.
Scene Builder: A visual tool for editing FXML files.
Java Code vs FXML: You can build UIs programmatically (Java) or declaratively (FXML). FXML promotes separation of concerns.

5: Opening FXML Files in Scene Builder

Once your project is open and you have configured the Scene Builder path (as shown in Part 3), you can easily edit your UI layout files directly from your IDE.

5.1: IntelliJ IDEA

IntelliJ IDEA project structure for JavaFX showing HelloApplication.java and hello-view.fxml

Default IntelliJ JavaFX project structure. Note the location of the main application class (1) and the FXML view file (2).

With your project open in IntelliJ IDEA and the Scene Builder path configured (as shown in Part 3.2), you can easily edit your UI layout files:

Navigate to your FXML file (e.g., src/main/resources/com/example/hello-view.fxml) in the IntelliJ Project tool window.
Right-click on the .fxml file.
Select Open In SceneBuilder from the context menu.

Right-clicking an FXML file in IntelliJ Project view showing the 'Open In SceneBuilder' option

Right-click the FXML file and choose 'Open In SceneBuilder' to visually edit the UI in IntelliJ IDEA

5.2: VS Code

Once your project is open in VS Code and you have configured the Scene Builder path (as shown in Part 3.3), you can easily edit your UI layout files:

Navigate to your FXML file (e.g., src/main/resources/com/example/primary.fxml) in the VS Code Explorer.
Right-click on the .fxml file.
Select Open in Scene Builder from the context menu.

Right-clicking an FXML file in VS Code Explorer showing the 'Open in Scene Builder' option

Right-click the FXML file and choose 'Open in Scene Builder' to visually edit the UI

5.3: Editing with Scene Builder

Whether you open the .fxml file from IntelliJ IDEA or VS Code, Scene Builder will launch as a separate application. It loads your FXML file, allowing you to visually inspect the component hierarchy, drag and drop new UI elements from the library, and modify properties in the inspector pane. Any changes saved in Scene Builder are directly written back to the .fxml file in your project.

Scene Builder application showing a JavaFX view with Library, Hierarchy, and Inspector panes

Scene Builder interface after opening an FXML file for visual editing

6: Diagnosing Errors

6.1: JAVA_HOME and Path Issues

Issue: java: command not found or wrong Java version used for command-line tools.

Fix: Ensure JAVA_HOME points to your preferred JDK and your PATH includes JDK bin directory.

bash

# macOS/Linux: Add to ~/.zshrc or ~/.bash_profile
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
export PATH=$JAVA_HOME/bin:$PATH

# Windows: Set in System Properties > Environment Variables
# JAVA_HOME=C:\Program Files\Java\jdk-21
# Add %JAVA_HOME%\bin to PATH

After Changes: Restart your terminal and IDE and run java -version to verify.
Note: While JAVA_HOME influences many tools, IDEs and build systems may use their own configurations to determine which JDK to use (see sections below).

6.2: Managing Multiple Java Versions

Check Installed Versions:
- macOS: /usr/libexec/java_home -V
- Windows: Check C:\Program Files\Java
Watch Out for User vs. System JDKs (macOS):

Official installers often put them in /Library/Java/JavaVirtualMachines/ (system-wide).

Tools like JetBrains IDEs (e.g., IDEA), Homebrew (/opt/homebrew/opt/openjdk@21 on M-series Macs), or SDKMAN install them in the same path, but in your user directory ~/ with the same path otherwise.

The /usr/libexec/java_home tool (which helps set JAVA_HOME) might pick a different JDK even if you think you've set your user one in your shell config. You can diagnose this with java -version and /usr/libexec/java_home -V to see which is active. If you find duplicates, removing the one(s) you don't need is usually the simplest fix.

Remove Unwanted Versions:
- macOS: sudo rm -rf /Library/Java/JavaVirtualMachines/jdk-17.jdk
- Homebrew: brew uninstall openjdk@17
- Windows: Use Control Panel > Programs > Uninstall
After Removal: Update your JAVA_HOME to point to your preferred version.

6.3: IDE-Specific JDK Settings

Important: IDEs often maintain their own JDK settings independent of JAVA_HOME.
VS Code:
1. Command Palette: "Java: Configure Java Runtime"
2. Select project and installed JDK version
3. Clean cache: "Java: Clean Java Language Server Workspace" if needed
IntelliJ IDEA:
1. File > Project Structure (Cmd+; / Ctrl+Alt+Shift+S)
2. Set JDK under Project Settings > Project
3. Remove obsolete JDKs: Platform Settings > SDKs

IntelliJ IDEA Project Structure dialog showing JDK configuration

IntelliJ IDEA's Project Structure dialog for managing JDK references

6.4: Build System Configurations

Maven/Gradle Errors: "package does not exist" or version mismatches
Consistency Checks:
- Maven: mvn dependency:resolve
- Gradle: ./gradlew dependencies

Simple Fix: Match your build config version with your JDK version

xml

<!-- Maven: Ensure these match your JDK -->
<maven.compiler.release>21</maven.compiler.release>
<javafx.version>21</javafx.version>

Specifying Exact JDK:
- Simple approach: JAVA_HOME=/path/to/jdk mvn compile
- Gradle properties: org.gradle.java.home=/path/to/jdk
- For team consistency, use toolchains (Maven) or the Java toolchain API (Gradle)

Quick verification checks

After setup (and restarting your terminal/IDE), run these commands to confirm:

bash

# Verify JAVA_HOME (use correct command for your OS)
echo $JAVA_HOME   # macOS/Linux
echo %JAVA_HOME%  # Windows

# Verify java executable path (use correct command for your OS)
which java       # macOS/Linux
where java       # Windows

# Verify java version
java -version    # Should show JDK 21

If commands fail or show the wrong version, re-check environment variable settings.