Installation

Install the Kratos CLI and set up your development environment

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:

   macOS (Homebrew)

   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

   macOS (Homebrew)

   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:

macOS

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: kratos

This means $GOPATH/bin is not in your PATH. Add it:

export PATH="$PATH:$(go env GOPATH)/bin"

Command not found: protoc-gen-go-http

The 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 slow

Configure 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:

• Check the GitHub Issues
• Join the Discord Community
• Visit the Official Documentation
• Ask in the WeChat Group