Install Gatling for Java, Kotlin, Scala, or JavaScript

Gatling supports two distinct SDK families: the JVM SDK for Java, Kotlin, and Scala, and the JavaScript SDK for JavaScript and TypeScript. Both families expose the same load testing engine and produce identical HTML reports, so your choice of language is purely about ecosystem fit. This guide covers the installation process for every supported path: Maven, Gradle, sbt, and the JavaScript CLI. It also covers IDE setup and the standalone bundle for offline environments.

Java / Maven
Java / Gradle
Kotlin
Scala / sbt
JavaScript / TypeScript

Requirements

64-bit OpenJDK LTS, versions 11 through 25. Java 17 or 21 is recommended. The Azul JDK is a reliable choice.
Maven 3.6.3 or later — or use the Maven Wrapper bundled with the demo project (no system-wide Maven needed).
Git (optional, for cloning).

Verify your environment before continuing:

java -version
mvn -version

Gatling launch scripts and the Maven plugin respect the JAVA_HOME environment variable. If JAVA_HOME points at the wrong runtime you may see Unsupported major.minor version errors. Confirm the value before running tests.

Download the Starter Project

The quickest path is the official Maven demo project. It ships with a Maven Wrapper so you don’t need Maven installed separately.

git clone https://github.com/gatling/gatling-maven-plugin-demo-java.git
cd gatling-maven-plugin-demo-java
./mvnw clean install

Alternatively, download the ZIP archive directly from GitHub and extract it, then run ./mvnw clean install from the project root.

On Windows, replace ./mvnw with mvnw.cmd in all commands below.

Run the Bundled Demo

Confirm that everything is wired up correctly by executing the demo simulation:

./mvnw gatling:test

The plugin will prompt you to select a simulation if more than one is present, or run the only available one automatically. The HTML report is written to target/gatling/.To run a specific simulation without the interactive prompt:

./mvnw gatling:test -Dgatling.simulationClass=computerdatabase.ComputerDatabaseSimulation

Launch the Recorder

The Gatling Recorder captures browser traffic and converts it into a simulation script:

# Linux / macOS
./mvnw gatling:recorder

# Windows
mvnw.cmd gatling:recorder

Requirements

64-bit OpenJDK LTS, versions 11 through 25 (Java 17 or 21 recommended).
Gradle 7.6 or later — or use the Gradle Wrapper bundled with the demo project.

java -version
gradle -version

Download the Starter Project

git clone https://github.com/gatling/gatling-gradle-plugin-demo-java.git
cd gatling-gradle-plugin-demo-java
./gradlew gatlingRun

The HTML report lands in build/reports/gatling/.

Launch the Recorder

# Linux / macOS
./gradlew gatlingRecorder

# Windows
gradlew.cmd gatlingRecorder

Requirements

Same JVM prerequisites as Java: 64-bit OpenJDK LTS 11–25. Kotlin is compiled on the JVM — no separate Kotlin runtime installation is needed when using Maven or Gradle.

Starter Projects

Choose your preferred build tool:

git clone https://github.com/gatling/gatling-maven-plugin-demo-kotlin.git
cd gatling-maven-plugin-demo-kotlin
./mvnw gatling:test

Requirements

64-bit OpenJDK LTS 11–25.
sbt 1.x installed, or use the Maven/Gradle starter projects instead.

Scala simulations compiled with long method chains may trigger a StackOverflowError in the Scala compiler. Increase the compiler stack size by setting -Xss100M in your IDE’s Scala compiler settings or in the sbt configuration.

Starter Projects

git clone https://github.com/gatling/gatling-maven-plugin-demo-scala.git
cd gatling-maven-plugin-demo-scala
./mvnw gatling:test

Requirements

Node.js LTS v24 or later with npm v11 or later. Download from nodejs.org.

node -v
npm -v

Download the Starter Project

git clone https://github.com/gatling/gatling-js-demo.git
cd gatling-js-demo/javascript   # or: cd gatling-js-demo/typescript
npm install

Run the Bundled Demo

npx gatling run --simulation basicSimulation

The HTML report is written to target/gatling/.

Automate with package.json Scripts

Add shorthand scripts to package.json for convenience:

{
  "scripts": {
    "gatling:test": "npx gatling run --simulation basicSimulation",
    "gatling:recorder": "npx gatling recorder"
  }
}

Then run: npm run gatling:test

Launch the Recorder

npx gatling recorder

Standalone Bundle

The standalone bundle is intended for environments without internet access (for example, behind a corporate firewall). For all other situations, the Maven plugin is recommended — it is lighter and easier to commit to a Git repository.

The standalone bundle supports Java only — not Kotlin or Scala. For those languages, use a Maven, Gradle, or sbt project.

The bundle is based on a Maven Wrapper. Extract it, then open the project in an IDE such as IntelliJ IDEA. Bundle directory structure:

Path	Purpose
`src/test/java`	Your simulation source files (respect package hierarchy)
`src/test/resources`	Feeder files, request body templates, Gatling/Logback config
`pom.xml`	Maven project descriptor
`target/`	Generated test results

Windows users: do not place the bundle in the Programs folder (permission issues). Use 7-zip to extract the archive — the built-in Windows zip tool will not work correctly.

IDE Setup

IntelliJ IDEA
VS Code

IntelliJ IDEA Community Edition supports Java, Kotlin, Maven, and Gradle out of the box. Open the project folder and IntelliJ will detect the build tool automatically.For Scala with sbt, install the Scala plugin from the JetBrains Marketplace. After installing it, increase the Scala compiler stack size to avoid StackOverflowError during compilation:

Go to Settings → Build, Execution, Deployment → Compiler → Scala Compiler.
Add -Xss100M to the compiler options.

VS Code works well for all Gatling SDK languages. Install the following extensions for the best experience:JVM languages:

Extension Pack for Java (Java + Maven/Gradle support)
Kotlin
Metals (Scala language server)

JavaScript / TypeScript:

ESLint
Prettier
JavaScript and TypeScript Nightly

Recommended .vscode/settings.json for JavaScript/TypeScript projects:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

Next Steps

First Simulation

Write your first end-to-end simulation step by step with full explanations.

Low-Code Tools

Import a Postman collection or use the browser recorder to generate simulations automatically.

Introduction

Tutorials

Core Concepts

Load Testing Concepts

Install Gatling for Java, Kotlin, Scala, or JavaScript

Requirements

Download the Starter Project

Run the Bundled Demo

Launch the Recorder

Requirements

Download the Starter Project

Launch the Recorder

Requirements

Starter Projects

Requirements

Starter Projects

Requirements

Download the Starter Project

Run the Bundled Demo

Automate with package.json Scripts

Launch the Recorder

Standalone Bundle

IDE Setup

Next Steps

First Simulation

Low-Code Tools

Build docs developers (and LLMs) love

Introduction

Tutorials

Core Concepts

Load Testing Concepts

Documentation Index

​Requirements

​Download the Starter Project

​Run the Bundled Demo

​Launch the Recorder

​Requirements

​Download the Starter Project

​Launch the Recorder

​Requirements

​Starter Projects

​Requirements

​Starter Projects

​Requirements

​Download the Starter Project

​Run the Bundled Demo

​Automate with package.json Scripts

​Launch the Recorder

​Standalone Bundle

​IDE Setup

​Next Steps

First Simulation

Low-Code Tools

Build docs developers (and LLMs) love

Requirements

Download the Starter Project

Run the Bundled Demo

Launch the Recorder

Requirements

Download the Starter Project

Launch the Recorder

Requirements

Starter Projects

Requirements

Starter Projects

Requirements

Download the Starter Project

Run the Bundled Demo

Automate with package.json Scripts

Launch the Recorder

Standalone Bundle

IDE Setup

Next Steps