Skip to main content
CockroachDB is a distributed SQL database written in Go. The build system uses Bazel, but most operations are wrapped through the ./dev tool for convenience.

​
Prerequisites

Before building CockroachDB from source, ensure you have the required dependencies installed.
1

Install Dependencies

Follow the bootstrap script for your platform:
Debian/Ubuntu
./build/bootstrap/bootstrap-debian.sh
This installs:
  • Go (correct version as specified in the project)
  • Bazel build system
  • Required development libraries
2

Clone the Repository

git clone https://github.com/cockroachdb/cockroach.git
cd cockroach
3

Verify Installation

Check that the ./dev tool is available:
./dev --help
The ./dev tool automatically builds itself on first run. It uses Bazel internally and caches the binary at bin/dev-versions/dev.$VERSION.

​
Building the CockroachDB Binary

The ./dev build command is the primary way to build CockroachDB components.

​
Full Binary with UI

./dev build cockroach
This builds the complete CockroachDB binary including the web UI. The output is placed in artifacts/cockroach.
Building the full binary is slow (can take 10+ minutes on first build). Only do this when you need the complete package.
./dev build short
This builds CockroachDB without the web UI and is significantly faster. Use this for most development work.

​
Building Specific Packages

# Build a specific package
./dev build pkg/util/log

​
Build Options and Flags

The ./dev build command supports various options: 
./dev build --help

​
Common Build Scenarios

Build for different platforms:
# Cross-compile for Linux ARM
./dev build cockroach --cross=linuxarm

# Cross-compile standard Linux build
./dev build cockroach --cross
Cross-compiled binaries are placed in the artifacts/ directory.
For geospatial support:
./dev build cockroach geos --cross
This builds both the cockroach binary and required libgeos libraries.
To build a deployment Docker image:
  1. Build the cross-compiled binary: 
    ./dev build cockroach geos --cross
  2. Copy artifacts to deploy directory: 
    cp ./artifacts/{cockroach,libgeos.so,libgeos_c.so} ./build/deploy
cp ./LICENSE ./licenses/THIRD-PARTY-NOTICES.txt ./build/deploy
  3. Build the Docker image: 
    cd ./build/deploy
docker build -t localhost/cockroach:latest .

​
Using the Bazel Builder Container

For consistent builds across platforms, use the bazelbuilder Docker container: 
./dev builder
This drops you into a containerized environment with all build dependencies pre-installed.
Ensure Docker grants at least 4GB of RAM to containers. The default 2GB limit may be insufficient for building CockroachDB.

​
Build Performance Tips

Incremental Builds

Bazel performs incremental builds automatically. Subsequent builds only recompile changed components.

Remote Cache

CockroachDB uses remote caching for Bazel. Most dependencies are pre-cached, speeding up initial builds.

Build Short

Use ./dev build short instead of full builds during development. It’s 3-5x faster.

Specific Packages

Build only the packages you’re working on rather than the entire binary.

​
Troubleshooting Build Issues

​
Build Fails with Memory Errors

Increase Docker memory allocation or reduce parallelism: 
# Reduce Bazel parallelism
bazel build --jobs=4 //pkg/cmd/cockroach

​
Stale Build Artifacts

Clean and rebuild: 
# Force rebuild of dev tool
DEV_FORCE_REBUILD=1 ./dev build short

# Clean Bazel cache (use sparingly)
bazel clean

​
Missing Dependencies

Re-run the bootstrap script: 
./build/bootstrap/bootstrap-debian.sh

​
Next Steps

Running Tests

Learn how to run the test suite

Code Structure

Understand the codebase organization

Contributing

Read the contribution guidelines

Code Generation

Learn about generated code

Build docs developers (and LLMs) love

Get started for freeTalk to us