Skip to main content
This guide will help you set up your local development environment for contributing to Temporal Server.

​
Prerequisites

​
Build Prerequisites

1

Install Go

Temporal Server requires Go 1.26.0 or later (check go.mod for the current minimum version).macOS:
brew install go
Ubuntu:
sudo apt install golang
Verify installation:
go version
2

Install Protocol Buffers Compiler (Optional)

Only required if you plan to modify .proto files.macOS:
brew install protobuf
Other platforms: Download from the protoc release page.
3

Install Temporal CLI

The Temporal CLI is used for interacting with the server during development.Homebrew:
brew install temporal
Manual install: Download from github.com/temporalio/cli
4

Install Docker

Docker is required for running runtime dependencies (databases, Elasticsearch, etc.).Follow the Docker installation guide for your platform.
It’s possible to run dependencies directly on the host OS instead of Docker. See the run dependencies on host guide for details.

​
Windows Development

For Windows developers, install Windows Subsystem for Linux 2 (WSL2) and Ubuntu, then follow the Ubuntu instructions above.

​
Clone the Repository

Temporal uses Go modules, so there’s no dependency on the $GOPATH variable. Clone the repository to your preferred location: 
git clone https://github.com/temporalio/temporal.git
cd temporal

​
Start Runtime Dependencies

The Temporal server can run with SQLite as an in-memory database, making runtime dependencies optional. However, for full-featured development and testing, start the optional dependencies: 
make start-dependencies
This starts the following services via Docker Compose:
  • Cassandra (database)
  • PostgreSQL (database)
  • MySQL (database)
  • Elasticsearch (visibility)
  • Temporal Web UI (available at localhost:8080)
  • Grafana (metrics, available at localhost:3000)
To stop the dependencies: 
make stop-dependencies

​
Verify Your Setup

Verify your environment is correctly configured: 
# Check Go version
go version

# Check Docker is running
docker ps

# Verify you can access the repository
ls -la

​
Next Steps

Once your environment is set up:

​
Troubleshooting

​
Docker Performance on macOS

If you experience slow Docker performance on macOS, consider running dependencies directly on your host system. See run dependencies on host for database-specific setup instructions:

​
Go Module Issues

If you encounter Go module-related errors: 
go mod tidy
go mod download

Build docs developers (and LLMs) love

Get started for freeTalk to us