Setup

Check System Requirements

Make sure your computer meets the following requirements:

  • 64-bit operating system: Windows, Linux or macOS.

  • Memory – at least 16 GB.

  • Hard drive free space – at least 20 GB.

Install Jmix Studio

Jmix Studio is implemented as a plugin for IntelliJ IDEA. The minimal supported IntelliJ IDEA version is 2025.3.

If you don’t have IntelliJ IDEA installed yet, download Community edition from the JetBrains website and install it.

After IntelliJ IDEA has been installed, do the following:

  1. Start IntelliJ IDEA (2025.3 or newer).

  2. On the startup screen of the IDE, click the Plugins button.

    If you have any project open, use the main menu: File → Settings (on Windows and Linux) or IntelliJ IDEA → Preferences (on macOS). Then switch to the Plugins section.

  3. Switch to the Marketplace tab.

  4. Enter "jmix" into the search field. You will see the Jmix plugin in the search results.

  5. Click Install and follow the further instructions of the IDE.

    install plugin

In case you need to configure internet access via a proxy server or install non-standard Studio builds, visit the Studio installation section.

To access premium Studio features, configure a subscription in the subscription dialog window.

Install Java Development Kit (JDK)

Download JDK version 21 or 25 (for example, Eclipse Temurin) and install it to a directory suggested by the installer. This is enough for creating and running applications from the IDE.

With Jmix 3.0, you can build applications using Java 21 or 25 from any vendor. However, we don’t recommend an OpenJ9-based JDK due to the problems it has caused in the past.

To run Jmix applications from the terminal, set the JAVA_HOME environment variable as described below.

  • On Windows, create the JAVA_HOME variable with the path to the installed JDK root directory at Computer → Properties → Advanced System Settings → Advanced → Environment variables. The variable should be added to the System variables list.

  • On macOS and Linux set JAVA_HOME in ~/.bash_profile or another appropriate file of your shell, for example:

    export JAVA_HOME="/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home"

  • Restart the computer to make sure the environment variable has taken effect.

  • Check that the environment variable is set correctly by running the following command in the console:

    On Windows
    "%JAVA_HOME%\bin\java" -version
    On Linux and macOS
    "$JAVA_HOME/bin/java" -version

    The command should return the Java version, e.g. 21.0.2.

If you connect to the internet via a proxy server, some Java system properties must be passed to the JVM running development tools and Gradle. Configure these properties using Jmix Studio.

Coding with AI Agents

You can speed up the development of Jmix applications by using AI coding agents.

To enable an AI agent to work effectively with Jmix patterns, architecture, and best practices, we recommend using the Jmix Agent Toolkit. This toolkit provides:

  • Architecture Overview: Deep understanding of Jmix-specific patterns.

  • Agent Skills: Specialized knowledge for developing entities, UI views, data access, and more.

  • Development Workflow: Optimized instructions for AI agents to follow Jmix-specific mandatory rules.

  • Configuration of recommended MCP servers and CLI tools.

Use the AI Agents Toolkit action in Studio or the CLI script to install the toolkit.

Using Jmix CLI

You can create Jmix projects without an IDE using Jmix CLI. It is a command-line tool that uses the same project templates as Studio. You can run it in a terminal, from a script, or let an AI coding agent run it.

Install the CLI on macOS or Linux:

curl -fsSL https://github.com/jmix-framework/jmix-cli/releases/latest/download/install.sh | bash

On Windows, run in PowerShell:

irm https://github.com/jmix-framework/jmix-cli/releases/latest/download/install.ps1 | iex

The CLI includes its own Java runtime, so you do not need a JDK to run it. To build the created project, you need a JDK, and the CLI can help you install it.

Run jmix to start the interactive wizard. It lets you select a project template, locales, add-ons and the project location.

To create a project from a script or by an AI agent, pass the parameters on the command line with the --non-interactive option:

jmix new demo --non-interactive \
    --template application \
    --locales en,de \
    --addons quartz,german-translation

At the end of each run, the CLI prints the jmix new command that creates the same project in non-interactive mode. Run jmix new --help to see all options.

Commercial add-ons require a subscription. The CLI expects that the credentials for the premium repository are already set up in your environment.

The created project includes the Jmix Agent Toolkit. Use the --no-agents-toolkit option to create a project without it.

Troubleshooting

Depending on the size of your project, you may need to increase available memory for the IntelliJ IDEA and Gradle processes.

  1. In IntelliJ IDEA, open Help → Edit Custom VM Options…​ and edit the -Xmx parameter (it’s usually on top). The recommended value is 2048m or more, for example:

    -Xmx2048m

  2. Edit the ~/.gradle/gradle.properties file and set the -Xmx parameter in the org.gradle.jvmargs property. The recommended value is 2048m or more, for example:

    org.gradle.jvmargs=-Xmx2048m