Skip to main content
This guide covers everything you need to install and configure the Cosmos SDK for blockchain development.

​
System Requirements

​
Go Version

Cosmos SDK requires Go 1.25.7 or later. The SDK uses the latest Go features for optimal performance and security.
We advise always using the latest maintained Go version for building Cosmos SDK applications.

​
Operating Systems

The Cosmos SDK is supported on:
  • Linux (recommended for production)
  • macOS (recommended for development)
  • Windows (via WSL2)

​
Hardware Requirements

Minimum specifications for development:
  • CPU: 2+ cores
  • RAM: 4GB minimum, 8GB recommended
  • Disk: 20GB available space
  • Network: Stable internet connection for syncing
Production nodes require significantly more resources depending on the chain. Check your specific chain’s requirements.

​
Installation Methods

Building from source gives you the latest features and allows customization.
1

Install Go

Download and install Go 1.25.7 or later from go.dev/dl.Verify your installation:
go version
Expected output:
go version go1.25.7 linux/amd64
2

Configure Go Environment

Set up your Go workspace by adding these to your shell profile (~/.bashrc, ~/.zshrc, etc.):
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin
Apply the changes:
source ~/.bashrc  # or ~/.zshrc
3

Clone the Repository

Clone the Cosmos SDK repository:
git clone https://github.com/cosmos/cosmos-sdk.git
cd cosmos-sdk
Optionally, check out a specific version:
git fetch --tags
git checkout v0.53.0  # Replace with desired version
4

Build and Install

Build the SimApp example application:
make install
This compiles the simd binary and installs it to $GOPATH/bin.
The build process uses build tags defined in the Makefile. Default tags include netgo for static linking.
5

Verify Installation

Confirm the binary is installed correctly:
simd version
You should see version information and the commit hash.

​
Method 2: Install from Release

For stable releases, you can download pre-built binaries: 
# Download the latest release binary for your platform
wget https://github.com/cosmos/cosmos-sdk/releases/download/v0.53.0/simd-linux-amd64

# Make it executable
chmod +x simd-linux-amd64

# Move to PATH
sudo mv simd-linux-amd64 /usr/local/bin/simd

# Verify
simd version

​
Method 3: Using Docker

For containerized development: 
# Pull the official image
docker pull ghcr.io/cosmos/simapp:latest

# Run a container
docker run -it ghcr.io/cosmos/simapp:latest simd version

​
Build Options

The Cosmos SDK supports various build options through environment variables:

​
Database Backend Selection

make install

​
Ledger Support

Enable hardware wallet support: 
LEDGER_ENABLED=true make install
Ledger support requires gcc installed on Linux/macOS. On Windows, you need gcc.exe.

​
Cross-Platform Builds

Build for different platforms: 
make build-linux-amd64
Binaries are output to the build/ directory.

​
Debug Builds

For debugging with symbols: 
COSMOS_BUILD_OPTIONS=debug make install

​
Dependencies

​
Required System Packages

Install build dependencies for your platform: 
sudo apt update
sudo apt install -y build-essential git wget

​
Optional: Development Tools

Useful tools for development: 
# Install mockgen for generating test mocks
go install go.uber.org/mock/mockgen@latest

# Install golangci-lint for code linting
go install github.com/golangci/golangci-lint/v2/cmd/[email protected]

# Install buf for protobuf management
go install github.com/bufbuild/buf/cmd/buf@latest

​
Environment Setup

​
Set Default Node Home

Customize where blockchain data is stored: 
export DAEMON_HOME=$HOME/.mychain
export DAEMON_NAME=myappd

​
Configure Shell Completion

Enable command-line autocomplete: 
simd completion bash > /etc/bash_completion.d/simd

​
Verification Steps

After installation, verify your setup:

​
1. Check Binary Installation

which simd
# Expected: /home/user/go/bin/simd

simd version --long
Expected output includes: 
name: sim
server_name: simd
version: 0.53.0
commit: abc123...
go: go1.25.7
build_tags: netgo

​
2. Test Basic Commands

# Show help
simd --help

# Show available commands
simd --help | grep "Available Commands"

​
3. Initialize a Test Chain

# Initialize without starting
simd init testnode --chain-id test

# Verify config was created
ls ~/.simapp/config/

​
4. Check Go Module

For custom applications using the SDK as a dependency: 
go list -m github.com/cosmos/cosmos-sdk

​
Troubleshooting

​
Issue: simd: command not found

Solution: Ensure $GOPATH/bin is in your PATH: 
echo $PATH | grep -o "$GOPATH/bin"
If not found, add to your shell profile: 
export PATH=$PATH:$GOPATH/bin

​
Issue: Go Version Too Old

Solution: Update Go to 1.25.7 or later: 
# Remove old version
sudo rm -rf /usr/local/go

# Download and install new version
wget https://go.dev/dl/go1.25.7.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.25.7.linux-amd64.tar.gz

# Verify
go version

​
Issue: Build Fails with Ledger Errors

Solution: Disable Ledger support if you don’t need it: 
LEDGER_ENABLED=false make install
Or install GCC: 
sudo apt install -y gcc

​
Issue: cannot find module Error

Solution: Ensure dependencies are downloaded: 
go mod download
go mod verify

​
Issue: Disk Space

Solution: Clean build artifacts: 
make clean
go clean -cache -modcache -testcache

​
Additional Tools

​
Cosmovisor

Automatic binary upgrade management: 
make cosmovisor
# Binary installed to: $GOPATH/bin/cosmovisor

​
Confix

Configuration file migration tool: 
make confix
# Binary installed to: $GOPATH/bin/confix

​
Building Custom Applications

To use Cosmos SDK in your own project:

​
1. Initialize Go Module

mkdir mychain
cd mychain
go mod init github.com/username/mychain

​
2. Add Cosmos SDK Dependency

go get github.com/cosmos/[email protected]

​
3. Import in Your Code

import (
    "github.com/cosmos/cosmos-sdk/types"
    "github.com/cosmos/cosmos-sdk/client"
)

​
Next Steps

Quickstart

Initialize and run your first blockchain node

Application Architecture

Learn how Cosmos SDK applications are structured

Building Modules

Start building custom blockchain modules

Building Chains

Deep dive into creating blockchain applications

​
Staying Updated

​
Check for Updates

cd cosmos-sdk
git fetch --tags
git tag --sort=-version:refname | head -n 5

​
Upgrade to New Version

git checkout v0.53.0  # Replace with target version
make install
Always review the CHANGELOG and migration guides before upgrading.

​
Community Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us