Getting started

This page walks through cloning the repository, getting a local build going, and running Elasticsearch from source. The authoritative references are BUILDING.md, CONTRIBUTING.md, and TESTING.asciidoc in the repo root — this page summarizes them.

Prerequisites

• JDK 25 — the build expects a JDK 25 install referenced by JAVA_HOME. The Gradle build provisions matching JDKs for tests using elasticsearch.runtime-jdk-provision, but a JDK 25 in JAVA_HOME is required for Gradle itself.
• Docker — required for some packaging tasks and tests (distribution/docker, qa/... Docker fixtures).
• Git LFS is not used.
• IDE — IntelliJ IDEA 2020.1+ is the supported IDE; configure imports and the Elastic license header per CONTRIBUTING.md.

The build uses the bundled Gradle wrapper. Do not install Gradle separately.

Clone

git clone https://github.com/elastic/elasticsearch.git
cd elasticsearch

Build a local distribution

./gradlew localDistro

The task prints the output path under distribution/archives/local-tar/build/install. To target a specific OS:

./gradlew :distribution:archives:linux-tar:assemble
./gradlew :distribution:archives:darwin-tar:assemble
./gradlew :distribution:archives:windows-zip:assemble

Run Elasticsearch from source

./gradlew :run

The run task starts a single-node dev cluster with X-Pack security enabled. After it logs started, send requests with:

# Built-in elastic user
curl -u elastic:password http://localhost:9200

# Pre-configured admin user (exists in the dev cluster)
curl -u elastic-admin:elastic-password http://localhost:9200

To run without security:

./gradlew :run -Dtests.es.xpack.security.enabled=false

To run a multi-node cluster:

./gradlew :run -PnumNodes=3

Run the test suite

The project's testing handbook is TESTING.asciidoc. Common entry points:

# Full unit test suite
./gradlew test

# One subproject
./gradlew :server:test

# One class or method
./gradlew :server:test --tests org.elasticsearch.cluster.ClusterStateTests
./gradlew :server:test --tests org.elasticsearch.cluster.ClusterStateTests.testFoo

# Reproduce a flaky test from CI
./gradlew :server:test --tests <ClassName> -Dtests.seed=DEADBEEF -Dtests.iters=20

YAML REST tests:

./gradlew :rest-api-spec:yamlRestTest \
  --tests "org.elasticsearch.test.rest.ClientYamlTestSuiteIT.test {yaml=indices.create/10_basic/Create index}"

Integration tests follow the *IT naming convention and run via per-project internalClusterTest / javaRestTest / yamlRestTest tasks.

For ES|QL CSV tests:

./gradlew ":x-pack:plugin:esql:internalClusterTest" \
  --tests "org.elasticsearch.xpack.esql.CsvIT.*stats_first_last*"

See Testing for a deeper tour.

Format check / lint

./gradlew spotlessJavaCheck      # check
./gradlew spotlessApply          # apply
./gradlew :server:spotlessJavaCheck   # one project

spotlessApply also reorders imports and prunes unused ones. Run it before pushing.

The build also enforces forbidden-apis (banned JDK / unsafe methods) and precommit (a meta-task wiring license headers, third-party audit, dependency hygiene, and YAML validation).

Pick an issue to work on

Browse the GitHub issues filtered by good first issue or help wanted. Discuss the approach on the issue before sending a PR.

Editor setup

• IntelliJ IDEA: import as a Gradle project. Configure the Java code style XML from build-conventions/formatterConfig.xml. Insert the license header from build-conventions/elastic-license-2.0-AGPL-3.0-SSPL-1-license-header.txt (or the x-pack-only header for files under x-pack/).
• VS Code / IntelliJ Run config: launch org.elasticsearch.bootstrap.Elasticsearch with the JVM args printed by ./gradlew :run --debug-jvm.

Troubleshooting first-build failures

Symptom	Likely cause
Could not find tools.jar or wrong JDK	JAVA_HOME not pointing at JDK 25
Build hangs on Docker pull	Docker daemon not running or rate-limited
Spotless mass diff after pulling main	Run ./gradlew spotlessApply
forbidden-apis failure	Replace banned JDK call (e.g. java.io.File in tests)
Out-of-memory while testing	Set -Dtests.heap.size=4G and/or reduce -Dtests.jvms