Run Gatling Open-Source on Your Own Infrastructure

Gatling can be installed and run entirely on your own machine or CI infrastructure, independent of Gatling Enterprise’s cloud control plane. The open-source distribution is the foundation on which test scripts are written and validated locally before being packaged and deployed to Gatling Enterprise Edition for scaled cloud execution. This page covers the available installation methods, prerequisites, IDE configuration, and how to run your first simulation locally.

Prerequisites

JVM languages (Java, Kotlin, Scala)

Gatling runs on the Java Virtual Machine. Before installing, ensure you have:

Java: 64-bit OpenJDK LTS, versions 11 through 25. 32-bit JVMs and OpenJ9 are not supported. The Azul JDK is recommended.
Language support: Java, Kotlin, and Scala are supported from Gatling 3.7 onward. Earlier versions support Scala only.

Unless you are an experienced Scala or Kotlin developer, choose Java as your simulation language.

JavaScript / TypeScript

Gatling’s JavaScript SDK requires:

Node.js v24 or later (LTS versions only)
npm v11 or later (bundled with Node.js)

The JavaScript SDK currently covers the HTTP protocol only. Other Gatling protocols (JMS, MQTT, etc.) require the JVM distribution.

Installation methods

Maven (recommended)
Gradle
sbt (Scala)
JavaScript / TypeScript
Standalone Bundle

Maven is the recommended build tool for Java (and Kotlin) users. A Maven wrapper (mvnw) is included, so you do not need to install Maven separately.

Download the project ZIP

Download the Maven-Java demo project:

https://github.com/gatling/gatling-maven-plugin-demo-java/archive/refs/heads/main.zip

Unzip and open in your IDE

Extract the archive and open the folder in IntelliJ IDEA, VS Code, or your preferred IDE.

Run a simulation

# Linux / macOS
./mvnw gatling:test

# Windows
mvnw.cmd gatling:test

Gradle provides similar functionality to Maven, with a wrapper (gradlew) included.

Download the project ZIP

Download the Gradle-Java demo project:

https://github.com/gatling/gatling-gradle-plugin-demo-java/archive/refs/heads/main.zip

Unzip and open in your IDE

Extract the archive and open the folder in your IDE.

Run a simulation

Refer to the Gradle plugin documentation for run commands.

Download the JS demo project

https://github.com/gatling/gatling-js-demo/archive/refs/heads/main.zip

Navigate to the project subfolder

# For JavaScript
cd javascript

# For TypeScript
cd typescript

Install dependencies

npm install

Run the demo simulation

npx gatling run --simulation basicSimulation

The standalone bundle is intended for environments without internet access (e.g., behind a corporate firewall). It bundles Gatling with a Maven wrapper and is the heaviest installation option.

The bundle supports Java only (not Kotlin or Scala). For Kotlin or Scala simulations, use a Maven, Gradle, or sbt project instead.

Windows users: Do not place Gatling in the Programs folder (permission issues). Use 7-zip to extract the bundle—the built-in Windows zip tool may fail.

Download URL:

https://repo1.maven.org/maven2/io/gatling/highcharts/gatling-charts-highcharts-bundle/<version>/gatling-charts-highcharts-bundle-<version>-bundle.zip

Bundle folder structure:

Path	Purpose
`src/test/java/`	Place your simulation `.java` files here (respect package hierarchy)
`src/test/resources/`	Feeder files, request body templates, `gatling.conf`, `logback.xml`
`pom.xml`	Maven project descriptor
`target/`	Generated test results

IDE setup

IntelliJ IDEA

IntelliJ IDEA Community Edition includes Java, Kotlin, Maven, and Gradle support by default. For Scala and sbt, install the Scala plugin (available in the Community Edition). Increase the Scala compiler stack size to avoid StackOverflowError during compilation:

Open Settings → Build, Execution, Deployment → Compiler → Scala Compiler
Set the Xss JVM option to 100M

VS Code

Install the appropriate language extension for your chosen language:

Java: Java Extension Pack
Kotlin: Kotlin plugin
Scala: Metals

Running your first simulation locally

The demo projects include a pre-configured simulation you can run immediately to experience Gatling’s reports feature.

./mvnw gatling:test

Starting the Gatling Recorder

The Gatling Recorder captures browser interactions and converts them into a Gatling script.

./mvnw gatling:recorder

JAVA_HOME considerations

Gatling launch scripts and the Maven plugin honour the JAVA_HOME environment variable when set. If you encounter errors like Unsupported major.minor version, verify that JAVA_HOME points to a supported JDK (11–25) and that it matches the JDK reported by java -version.

Next steps

After validating your simulation locally, deploy it to Gatling Enterprise Edition for scaled, multi-location cloud runs:

Package Generation

Learn how to package your simulation for upload to Gatling Enterprise.

Test as Code

Create and configure a test-as-code run in the Enterprise UI.

Running Tests

Deployment

Administration

Analytics & Reports

Run Gatling Open-Source on Your Own Infrastructure

Prerequisites

JVM languages (Java, Kotlin, Scala)

JavaScript / TypeScript

Installation methods

IDE setup

IntelliJ IDEA

VS Code

Running your first simulation locally

Starting the Gatling Recorder

JAVA_HOME considerations

Next steps

Package Generation

Test as Code

Build docs developers (and LLMs) love

Running Tests

Deployment

Administration

Analytics & Reports

Documentation Index

​Prerequisites

​JVM languages (Java, Kotlin, Scala)

​JavaScript / TypeScript

​Installation methods

​IDE setup

​IntelliJ IDEA

​VS Code

​Running your first simulation locally

​Starting the Gatling Recorder

​JAVA_HOME considerations

​Next steps

Package Generation

Test as Code

Build docs developers (and LLMs) love

Prerequisites

JVM languages (Java, Kotlin, Scala)

JavaScript / TypeScript

Installation methods

IDE setup

IntelliJ IDEA

VS Code

Running your first simulation locally

Starting the Gatling Recorder

JAVA_HOME considerations

Next steps