Getting started

This page describes how to clone, build, test, and run etcd from this repository. It mirrors the contents of README.md and CONTRIBUTING.md and pinpoints the scripts and Make targets that drive each step.

Prerequisites

• Linux/amd64: the only officially supported development platform (CONTRIBUTING.md).
• Go: minimum version is the one declared in go.mod (.go-version records the toolchain). Recent etcd versions track Go 1.26.
• Build tools: make, protoc (v3.20.3), yamllint, jq, xz (see CONTRIBUTING.md for the apt commands).
• golangci-lint: installed automatically by make verify-lint via scripts/verify_golangci-lint_version.sh.
• Optional: goreman to run the local 3-node cluster from Procfile.

The repo also ships a .devcontainer/ for VS Code Codespaces, so you can skip toolchain setup if you use it.

Clone and build

git clone https://github.com/etcd-io/etcd.git
cd etcd

make build      # builds bin/etcd, bin/etcdctl, bin/etcdutl into ./bin

make build calls scripts/build.sh, which runs go build against each workspace module with -mod=readonly and -v. To cross-build all supported platforms run make build-all; to build a single OS/ARCH pair run e.g. make build-linux-arm64 (see Makefile).

Run a single-member etcd

./bin/etcd

This starts a member listening on :2379 for clients and :2380 for peer traffic, with a data directory of default.etcd/ in the current working directory (defaults defined in server/embed/config.go).

In a second shell:

./bin/etcdctl put hello world
./bin/etcdctl get hello

Run a local 3-member cluster

The repository ships a Procfile suitable for goreman:

go install github.com/mattn/goreman@latest
goreman start

This launches infra1, infra2, infra3 on ports 2379/12380, 22379/22380, 32379/32380. Optional learner promotion steps are documented in the Procfile comments.

Tests

Make target	What it runs	Defined by
make test-unit	Unit tests across all modules	scripts/test.sh (PASSES="unit")
make test-integration	In-process integration tests under tests/integration/	scripts/test.sh (PASSES="integration")
make test-e2e	End-to-end tests that spawn real binaries (tests/e2e/)	scripts/test.sh (PASSES="e2e")
make test-robustness	Robustness/fault-injection tests under tests/robustness/	tests/robustness/Makefile
make test-coverage	Builds with coverage instrumentation	scripts/test.sh (PASSES="build cov")
make fuzz	Run the libfuzz harnesses	scripts/fuzzing.sh

A single test pass can be filtered via the standard GO_TEST_FLAGS variable, e.g.:

GO_TEST_FLAGS='-run TestKVPut' make test-integration

Lint, formatting and verification

Target	Effect
make verify	Runs all the verifiers (BOM, lint, mod-tidy, shellcheck, proto annotations, yamllint, markdown markers, go workspace, ...)
make verify-lint	golangci-lint with the project's .golangci.yaml
make verify-bom	Confirms bill-of-materials.json matches go.mod files
make verify-shellcheck	Lints all shell scripts
make verify-yamllint	Lints YAML files using tools/.yamllint
make fix / make fix-*	Auto-fix the above where possible

The scripts/test.sh script is the single entry point for both tests and verification; each PASSES= value selects a different stage.

Where to find...

• Build: Makefile, scripts/build.sh, scripts/build_lib.sh, scripts/build_tools.sh
• Test driver: scripts/test.sh, scripts/test_lib.sh
• Release scripts: scripts/release.sh, scripts/release_mod.sh
• Protobuf regeneration: scripts/genproto.sh (and scripts/verify_genproto.sh)
• Vendored / mod tooling: tools/mod/
• Devcontainer: .devcontainer/devcontainer.json
• CI workflows: .github/workflows/ (etcd uses Kubernetes Prow for the bulk of CI; results live on https://testgrid.k8s.io/sig-etcd)