Setup and building

This page describes building the Pulsar master branch, which uses a Gradle build (migrated from Maven via PIP-463).

note

Maintenance branches (branch-4.2 and earlier) continue to use the Maven build (./mvnw). When working on a maintenance branch, follow the build instructions in that branch's README.md.

Prerequisites

Dependency	Description
Git	The source code of Pulsar is hosted on GitHub as a git repository. To work with the git repository, please install git. We highly recommend that you also set up a Git mergetool for resolving merge conflicts.
JDK	The source code of Pulsar is primarily written in Java. Building the master branch requires JDK 21 or 25 (the bytecode targets Java 17). It is recommended to use SDKMAN to install Corretto OpenJDK, see "Setting up JDKs using SDKMAN" for details.
Zip	The build process requires Zip as a utility tool.
Docker	Required only for building docker images and running the container-based integration tests.

There is no separate build tool to install: the repository includes the Gradle Wrapper, so a Gradle installation is not needed.

Windows

Pulsar does not officially support Windows. To run Pulsar on Windows, run it in Docker — see Run Pulsar in Docker.

For developing Pulsar on Windows, using WSL2 (Windows Subsystem for Linux) is strongly recommended. Use the most recent WSL2 version; legacy WSL (WSL 1) is not supported. Inside WSL2, follow the Linux instructions on this page as-is (./gradlew). IntelliJ IDEA supports developing in a WSL2 environment.

Clone

Clone the source code to your development machine:

git clone https://github.com/apache/pulsar

The following commands are assumed to be executed from the project root directory:

cd pulsar

Build

Compile and assemble everything, or a single module:

./gradlew assemble
./gradlew :pulsar-broker:assemble

Lint / verify (license headers, formatting, checkstyle) — run before pushing:

./gradlew rat spotlessCheck checkstyleMain checkstyleTest
./gradlew spotlessApply            # auto-fix license headers/formatting

For the Gradle build infrastructure and how to change build files (convention plugins, version catalog, configuration-cache rules), see ARCHITECTURE.md → Build infrastructure in the apache/pulsar repository.

Run tests

Always scope test runs with --tests — running a whole module's test task is slow:

# Run a single test class
./gradlew :pulsar-client-original:test --tests "ConsumerBuilderImplTest"
# Run a single test method
./gradlew :pulsar-client-original:test --tests "ConsumerBuilderImplTest.<methodName>"
# Run all tests in a specific package
./gradlew :pulsar-broker:test --tests "org.apache.pulsar.broker.admin.*"

note

Several Gradle project paths do not match their directory name because the Maven artifactId is preserved — for example, directory pulsar-client/ is the Gradle project :pulsar-client-original. Check settings.gradle.kts when a path is ambiguous. See ARCHITECTURE.md → Module name vs. directory name gotcha.

For test groups, test-related build properties, container-based integration tests, and running the full CI pipeline, see CONTRIBUTING.md → Running tests in the apache/pulsar repository and the Personal CI guide.

Run

Start a standalone Pulsar service (broker + bookie + metadata in one JVM):

bin/pulsar standalone

Connect

bin/pulsar-shell

Build docker images

Build the apachepulsar/pulsar:latest and apachepulsar/pulsar-all:latest docker images:

./gradlew docker        # or docker-all