Getting started

This page walks through cloning the repo, building Prometheus from source, and running the test suites. The user-facing operator documentation lives at https://prometheus.io/docs/ and in the documentation/ directory of this repo.

Prerequisites

Tool	Required version	Why
Go	The version pinned in go.mod (currently 1.25+, ideally 1.26 to match CI)	Build the server and tools.
Node	Version pinned in web/ui/.nvmrc (>= 22)	Build the React UI.
npm	>= 10	Install UI dependencies.
Docker	Optional	Build the docker image (make docker).
make	GNU make	Drives the whole build.
goyacc	golang.org/x/tools/cmd/goyacc@v0.6.0	Regenerate the PromQL parser. make install-goyacc installs it.

Everything is enforced by scripts/check-go-mod-version.sh and scripts/check-node-version.sh, which run as part of make test.

Clone and build

git clone https://github.com/prometheus/prometheus.git
cd prometheus

# Build everything: UI assets + Go binaries
make build

# Or, while iterating on Go code only (skips UI build)
go build ./cmd/prometheus
go build ./cmd/promtool

make build runs (in order): assets (npm install + UI build), npm_licenses (bundle licenses), assets-compress (gzip), then common-build from Makefile.common. The compiled UI is embedded into the binary via the builtinassets build tag (see web/ui/assets_embed.go).

If you do not want to rebuild the UI every time, use the PREBUILT_ASSETS_STATIC_DIR make variable to point at an existing web/ui/static tarball — see the build instructions in README.md.

Run the server

./prometheus --config.file=documentation/examples/prometheus.yml

Prometheus listens on :9090 by default. The web UI is at /, the HTTP API at /api/v1/.... Use --agent to run in agent mode (no local TSDB or query engine).

The full flag list is generated into docs/command-line/prometheus.md via make cli-documentation.

Run the tests

# Go tests + UI tests + lint + node version + parser-up-to-date
make test

# Go tests only (skip UI)
make test GO_ONLY=1

# Race-detector for the most concurrency-sensitive packages
go test --tags=slicelabels -race ./cmd/prometheus ./model/textparse ./prompb/...

# TSDB-specific run with isolation disabled (CI runs this in addition)
go test ./tsdb/ -test.tsdb-isolation=false

The CI definition is in .github/workflows/ci.yml. It runs the test suite on quay.io/prometheus/golang-builder:1.26-base, builds the docker image, runs the UI tests via make ui-test, executes Windows tests on windows-latest, and runs golangci-lint on each PR.

Lint

make lint

This runs golangci-lint with the configuration in .golangci.yml (which enables gocritic, errcheck, revive, staticcheck, unconvert, whitespace, and several others) plus UI lint (make ui-lint).

Common workflows

Regenerate the PromQL parser

make install-goyacc   # one-time
make parser           # regenerates promql/parser/generated_parser.y.go

promql/parser/generated_parser.y is the goyacc grammar. make check-generated-parser (run by CI) verifies the generated file is up to date.

Regenerate UI helpers

make generate-promql-functions

This runs gen_functions_list and gen_functions_docs in web/ui/mantine-ui/src/promql/tools to keep functionSignatures.ts and functionDocs.tsx in sync with the Go function definitions in promql/functions.go and the markdown in docs/querying/functions.md.

UI development server

cd web/ui
npm install            # only the first time
npm start              # serves the new (Mantine) UI on http://localhost:5173
                       # API requests proxy to http://localhost:9090

See web/ui/README.md for details, including how to point the dev server at a remote Prometheus.

Build a docker image

make promu                      # build the promu helper if not present
promu crossbuild -p linux/amd64
make npm_licenses
make common-docker-amd64

The make docker target is intended for the official CI release pipeline and may not produce a working image when run directly — see the warning in README.md.

Where to put your changes

The general PR rule from AGENTS.md is one area per PR with the area used as the title prefix:

tsdb: <description>            # changes to tsdb/
promql: <description>          # changes to promql/
discovery/<sd>: <description>  # one specific SD
ui: <description>              # changes to web/ui
ci: <description>              # changes to .github/workflows

Read How to contribute before opening the PR.