Skip to main content

​
Installation

This guide walks you through installing the Kratos CLI and all required dependencies for building microservices with Kratos.

​
Prerequisites

​
Go Programming Language

Kratos requires Go 1.22 or higher.
1

Check your Go version

Verify that Go is installed:
go version
You should see output like:
go version go1.22.0 linux/amd64
2

Install or upgrade Go

If you need to install or upgrade Go:
brew install go
3

Configure GOPROXY (Optional but recommended)

For faster dependency downloads, especially in China:
go env -w GOPROXY=https://goproxy.io,direct
Or use other proxy services:
# Google's proxy
go env -w GOPROXY=https://proxy.golang.org,direct

# Alibaba's proxy (for China)
go env -w GOPROXY=https://mirrors.aliyun.com/goproxy/,direct

​
Install Protocol Buffers Compiler

Kratos uses Protocol Buffers for API definitions and code generation.
1

Install protoc

brew install protobuf
2

Verify installation

protoc --version
Expected output:
libprotoc 3.21.12

​
Install Kratos CLI

The Kratos CLI provides commands for project scaffolding, code generation, and development workflows.
1

Install the kratos command

Use go install to install the latest version:
go install github.com/go-kratos/kratos/cmd/kratos/v2@latest
This installs the kratos binary to your $GOPATH/bin directory.
2

Add GOPATH/bin to PATH

Ensure $GOPATH/bin is in your PATH:
# Add to ~/.bashrc, ~/.zshrc, or equivalent
export PATH="$PATH:$(go env GOPATH)/bin"
Reload your shell configuration:
source ~/.bashrc  # or ~/.zshrc
3

Verify installation

kratos --version
You should see the Kratos version:
kratos version v2.x.x
4

Upgrade Kratos CLI

To upgrade to the latest version:
kratos upgrade
Or manually reinstall:
go install github.com/go-kratos/kratos/cmd/kratos/v2@latest

​
Install Protocol Buffer Plugins

Kratos requires several protoc plugins for generating Go code from .proto files.
1

Install required plugins

# Standard Go protobuf plugin
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

# gRPC plugin
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# Kratos HTTP plugin
go install github.com/go-kratos/kratos/cmd/protoc-gen-go-http/v2@latest

# Kratos errors plugin
go install github.com/go-kratos/kratos/cmd/protoc-gen-go-errors/v2@latest

# OpenAPI documentation plugin (optional)
go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest
2

Verify plugin installation

Check that the plugins are in your PATH:
which protoc-gen-go
which protoc-gen-go-grpc
which protoc-gen-go-http
All commands should return paths to the installed binaries.

​
Optional Development Tools

​
Wire (Dependency Injection)

Kratos projects use Wire for compile-time dependency injection: 
go install github.com/google/wire/cmd/wire@latest

​
Air (Live Reload)

For automatic service restart during development: 
go install github.com/cosmtrek/air@latest
Create an .air.toml configuration: 
air init
Then run with: 
air

​
grpcurl (gRPC Testing)

Command-line tool for testing gRPC services: 
brew install grpcurl

​
Using Docker (Alternative Setup)

If you prefer not to install dependencies locally, you can use Docker:
1

Create a development container

docker run -it --rm \
  -p 8000:8000 \
  -p 9000:9000 \
  --workdir /workspace \
  golang:1.22
2

Install dependencies in container

Inside the container:
# Install protoc
apt-get update && apt-get -y install protobuf-compiler

# Configure Go proxy
export GOPROXY=https://goproxy.io,direct

# Install Kratos CLI
go install github.com/go-kratos/kratos/cmd/kratos/v2@latest
kratos upgrade
3

Create your project

kratos new helloworld
cd helloworld
go mod tidy
kratos run

​
Verify Your Installation

Create a test project to verify everything is working: 
# Create a new project
kratos new test-service
cd test-service

# Install dependencies
go mod tidy

# Generate code from protos
make api

# Run the service
kratos run
If the service starts without errors, your installation is complete!

​
Troubleshooting

Command not found: kratosThis means $GOPATH/bin is not in your PATH. Add it:
export PATH="$PATH:$(go env GOPATH)/bin"
Command not found: protoc-gen-go-httpThe Kratos protoc plugins are not installed. Run:
go install github.com/go-kratos/kratos/cmd/protoc-gen-go-http/v2@latest
go install github.com/go-kratos/kratos/cmd/protoc-gen-go-errors/v2@latest
Module download too slowConfigure a faster Go proxy:
go env -w GOPROXY=https://goproxy.io,direct

​
Next Steps

Now that you have Kratos installed:

Quick Start

Create your first Kratos service

CLI Reference

Learn about all Kratos CLI commands

Project Structure

Understand the generated project layout

Configuration

Configure your Kratos application

​
Keeping Up to Date

To stay current with Kratos: 
# Update the CLI
kratos upgrade

# Update dependencies in your project
go get -u github.com/go-kratos/kratos/v2@latest
go mod tidy

# Regenerate code after updates
make api

​
Getting Help

If you encounter issues:

Build docs developers (and LLMs) love

Get started for freeTalk to us