Installation guide

YugabyteDB can be installed on various platforms including Linux, macOS, Docker, and Kubernetes. This guide covers all installation methods with detailed instructions for each platform.

Choose your platform

Select the platform that best fits your needs:

Linux

Install on CentOS, Ubuntu, RHEL, or other Linux distributions

macOS

Install on macOS with Intel or Apple Silicon (M1/M2)

Docker

Run in containers for development and testing

Kubernetes

Deploy on Kubernetes for production workloads

Prerequisites by platform

Linux
macOS
Docker
Kubernetes

Operating system

YugabyteDB supports the following Linux distributions:

CentOS 7 or later
Red Hat Enterprise Linux (RHEL) 7 or later
Ubuntu 18.04, 20.04, 22.04
Amazon Linux 2
Oracle Linux 7 or later

System requirements

CPU: 2 cores minimum (4 cores recommended)
RAM: 4 GB minimum (8 GB recommended)
Disk: 10 GB free space minimum
Architecture: x86_64 or aarch64 (ARM)

Software dependencies

Install the required packages:

sudo yum install -y python3 wget

System configuration

Configure ulimits for optimal performance:

# Add to /etc/security/limits.conf
*                -       core            unlimited
*                -       data            unlimited
*                -       fsize           unlimited
*                -       sigpending      119934
*                -       memlock         64
*                -       rss             unlimited
*                -       nofile          1048576
*                -       msgqueue        819200
*                -       stack           8192
*                -       cpu             unlimited
*                -       nproc           12000
*                -       locks           unlimited

Proper ulimit configuration is critical. Without it, you may encounter file descriptor errors when creating many tablets.

Operating system

macOS 10.13 (High Sierra) or later
Apple Silicon (M1, M2, M3) fully supported
Intel processors fully supported

System requirements

CPU: 2 cores minimum (4 cores recommended)
RAM: 4 GB minimum (8 GB recommended)
Disk: 10 GB free space minimum

Software dependencies

Install Xcode command line tools:

xcode-select --install

Python 3 is typically pre-installed on macOS. Verify with:

python3 --version

macOS Monterey (12.0) and later enable AirPlay by default on port 7000. You’ll need to either disable AirPlay or configure YugabyteDB to use a different port.

Installation steps

Linux
macOS
Docker
Kubernetes

Download YugabyteDB

Download the appropriate package for your architecture:For x86_64 systems:

wget https://downloads.yugabyte.com/releases/2025.2.0.0/yugabyte-2025.2.0.0-b2-linux-x86_64.tar.gz

For ARM64/aarch64 systems:

wget https://downloads.yugabyte.com/releases/2025.2.0.0/yugabyte-2025.2.0.0-b2-el8-aarch64.tar.gz

Verify the download

Verify the checksum to ensure file integrity:

# For x86_64
echo "$(curl -L https://downloads.yugabyte.com/releases/2025.2.0.0/yugabyte-2025.2.0.0-b2-linux-x86_64-tar.gz.sha) *yugabyte-2025.2.0.0-b2-linux-x86_64.tar.gz" | shasum --check

# For ARM64  
echo "$(curl -L https://downloads.yugabyte.com/releases/2025.2.0.0/yugabyte-2025.2.0.0-b2-el8-aarch64-tar.gz.sha) *yugabyte-2025.2.0.0-b2-el8-aarch64.tar.gz" | shasum --check

You should see: OK

Extract the archive

tar xvfz yugabyte-2025.2.0.0-b2-linux-x86_64.tar.gz
cd yugabyte-2025.2.0.0/

Run post-install script

Configure YugabyteDB by running:

./bin/post_install.sh

This script:

Sets up the directory structure
Configures necessary libraries
Prepares the environment

Verify installation

Check that YugabyteDB is installed correctly:

./bin/yugabyted version

Expected output:

YugabyteDB version: 2025.2.0.0-b2
Build type: release

Add to PATH (optional)

For easier access, add YugabyteDB to your PATH:

echo 'export PATH=$PATH:/path/to/yugabyte-2025.2.0.0/bin' >> ~/.bashrc
source ~/.bashrc

Replace /path/to/ with your actual installation path.

Download YugabyteDB

Download the macOS package:

wget https://downloads.yugabyte.com/releases/2025.2.0.0/yugabyte-2025.2.0.0-b2-darwin-x86_64.tar.gz

The x86_64 package works on both Intel and Apple Silicon Macs (via Rosetta 2).

Extract the archive

tar xvfz yugabyte-2025.2.0.0-b2-darwin-x86_64.tar.gz
cd yugabyte-2025.2.0.0/

Run post-install script

./bin/post_install.sh

Handle macOS Gatekeeper

On first run, macOS may block unsigned binaries. Allow them:

# Remove quarantine attribute
xattr -r -d com.apple.quarantine yugabyte-2025.2.0.0

Alternatively, approve each binary in: System Preferences → Security & Privacy → General

Verify installation

./bin/yugabyted version

Configure port for macOS Monterey+

If you’re on macOS 12 (Monterey) or later:Option 1: Disable AirPlay receiving

System Preferences → Sharing
Uncheck “AirPlay Receiver”

Option 2: Use alternate port

./bin/yugabyted start --master_webserver_port=7001

Pull the Docker image

docker pull yugabytedb/yugabyte:2025.2.0.0-b2

Verify the image:

docker images | grep yugabyte

Create a persistent volume (optional)

For data persistence across container restarts:

mkdir ~/yb_data

Start the container

Basic (non-persistent):

docker run -d --name yugabyte \
  -p 7000:7000 \
  -p 9000:9000 \
  -p 15433:15433 \
  -p 5433:5433 \
  -p 9042:9042 \
  yugabytedb/yugabyte:2025.2.0.0-b2 \
  bin/yugabyted start --background=false

With persistent volume:

docker run -d --name yugabyte \
  --hostname yugabyte \
  -p 7000:7000 \
  -p 9000:9000 \
  -p 15433:15433 \
  -p 5433:5433 \
  -p 9042:9042 \
  -v ~/yb_data:/home/yugabyte/yb_data \
  yugabytedb/yugabyte:2025.2.0.0-b2 \
  bin/yugabyted start \
  --base_dir=/home/yugabyte/yb_data \
  --background=false

Always use --hostname with persistent volumes to avoid startup errors if the container is recreated.

Verify the container

Check that the container is running:

docker ps

Check cluster status:

docker exec -it yugabyte yugabyted status

Connect to the database

docker exec -it yugabyte bash -c '/home/yugabyte/bin/ysqlsh --host $(hostname)'

Docker Compose (multi-node)

For a 3-node cluster, create docker-compose.yml:

version: '3'
services:
  yb-master-1:
    image: yugabytedb/yugabyte:2025.2.0.0-b2
    container_name: yb-master-1
    command: bin/yb-master --master_addresses=yb-master-1:7100,yb-master-2:7100,yb-master-3:7100 --replication_factor=3
    ports:
      - "7000:7000"

  yb-master-2:
    image: yugabytedb/yugabyte:2025.2.0.0-b2
    container_name: yb-master-2
    command: bin/yb-master --master_addresses=yb-master-1:7100,yb-master-2:7100,yb-master-3:7100 --replication_factor=3

  yb-master-3:
    image: yugabytedb/yugabyte:2025.2.0.0-b2
    container_name: yb-master-3
    command: bin/yb-master --master_addresses=yb-master-1:7100,yb-master-2:7100,yb-master-3:7100 --replication_factor=3

  yb-tserver-1:
    image: yugabytedb/yugabyte:2025.2.0.0-b2
    container_name: yb-tserver-1
    command: bin/yb-tserver --tserver_master_addrs=yb-master-1:7100,yb-master-2:7100,yb-master-3:7100
    ports:
      - "9000:9000"
      - "5433:5433"

  yb-tserver-2:
    image: yugabytedb/yugabyte:2025.2.0.0-b2
    container_name: yb-tserver-2
    command: bin/yb-tserver --tserver_master_addrs=yb-master-1:7100,yb-master-2:7100,yb-master-3:7100

  yb-tserver-3:
    image: yugabytedb/yugabyte:2025.2.0.0-b2
    container_name: yb-tserver-3
    command: bin/yb-tserver --tserver_master_addrs=yb-master-1:7100,yb-master-2:7100,yb-master-3:7100

Start the cluster:

docker-compose up -d

Add Helm repository

helm repo add yugabytedb https://charts.yugabyte.com
helm repo update

Create namespace

kubectl create namespace yb-demo

Install YugabyteDB

Basic installation:

helm install yb-demo yugabytedb/yugabyte \
  --namespace yb-demo \
  --wait

Production installation with custom values:

helm install yb-demo yugabytedb/yugabyte \
  --namespace yb-demo \
  --set resource.master.requests.cpu=2 \
  --set resource.master.requests.memory=4Gi \
  --set resource.tserver.requests.cpu=4 \
  --set resource.tserver.requests.memory=8Gi \
  --set storage.master.size=100Gi \
  --set storage.tserver.size=500Gi \
  --set replicaCount=3 \
  --wait

Verify installation

Check pod status:

kubectl get pods -n yb-demo

Expected output:

NAME           READY   STATUS    RESTARTS   AGE
yb-master-0    2/2     Running   0          3m
yb-master-1    2/2     Running   0          3m
yb-master-2    2/2     Running   0          3m
yb-tserver-0   2/2     Running   0          3m
yb-tserver-1   2/2     Running   0          3m
yb-tserver-2   2/2     Running   0          3m

Connect to the database

kubectl exec -n yb-demo -it yb-tserver-0 -- ysqlsh -h yb-tserver-0.yb-tservers.yb-demo

Access the UI

Port-forward the master UI:

kubectl port-forward -n yb-demo svc/yb-master-ui 7000:7000

Open http://localhost:7000 in your browser.

Next steps

Quick start

Start a cluster and run your first queries

Core features

Explore YugabyteDB’s distributed capabilities

Production deployment

Deploy multi-node clusters for production

Build an app

Connect from your favorite programming language

Common issues

Installation fails on Linux

Missing dependencies:

# Install required packages
sudo yum install -y python3 wget  # CentOS/RHEL
sudo apt-get install -y python3 wget  # Ubuntu

Permission denied:

chmod +x bin/*

Insufficient ulimits:

ulimit -n 1048576
ulimit -u 12000

macOS Gatekeeper blocks binaries

Remove quarantine attribute:

xattr -r -d com.apple.quarantine /path/to/yugabyte-*

Or approve each binary in System Preferences → Security & Privacy.

Docker container won't start

Check resources:

Ensure Docker has at least 4 GB RAM
Verify CPU allocation (2+ cores)

Port conflicts:

# Find what's using the port
lsof -i :5433

# Stop conflicting services or use different ports
docker run -p 5434:5433 ...

Check logs:

docker logs yugabyte

Kubernetes pods not starting

Check storage:

kubectl get pvc -n yb-demo

Ensure your cluster has a default storage class or specify one:

--set storageClass=fast-ssd

Check resources:

kubectl describe pod yb-master-0 -n yb-demo

Nodes must have enough CPU and memory.

Upgrading YugabyteDB

To upgrade to a newer version:

Linux / macOS
Docker
Kubernetes

# Stop the current cluster
./bin/yugabyted stop

# Download and extract new version
wget https://downloads.yugabyte.com/releases/<new-version>/...
tar xvfz yugabyte-<new-version>.tar.gz

# Run post-install
cd yugabyte-<new-version>/
./bin/post_install.sh

# Start with existing data
./bin/yugabyted start --advertise_address=127.0.0.1

# Pull new image
docker pull yugabytedb/yugabyte:<new-version>

# Stop and remove old container
docker stop yugabyte
docker rm yugabyte

# Start with new image (use same volume for data persistence)
docker run -d --name yugabyte \
  -v ~/yb_data:/home/yugabyte/yb_data \
  yugabytedb/yugabyte:<new-version> ...

# Upgrade using Helm
helm upgrade yb-demo yugabytedb/yugabyte \
  --namespace yb-demo \
  --version <new-chart-version> \
  --wait

Always back up your data before upgrading. For production clusters, follow the rolling upgrade procedure.

Get Started

Core Concepts

Deployment

Develop

Operations

Security

Advanced Features

Choose your platform

Linux

macOS

Docker

Kubernetes

Prerequisites by platform

Operating system

System requirements

Software dependencies

System configuration

Operating system

System requirements

Software dependencies

Docker requirements

Resource allocation

Kubernetes requirements

Resource requirements per node

Supported Kubernetes platforms

Installation steps

Docker Compose (multi-node)

Next steps

Quick start

Core features

Production deployment

Build an app

Common issues

Upgrading YugabyteDB

Build docs developers (and LLMs) love

Get Started

Core Concepts

Deployment

Develop

Operations

Security

Advanced Features

​Choose your platform

Linux

macOS

Docker

Kubernetes

​Prerequisites by platform

​Operating system

​System requirements

​Software dependencies

​System configuration

​Operating system

​System requirements

​Software dependencies

​Docker requirements

​Resource allocation

​Kubernetes requirements

​Resource requirements per node

​Supported Kubernetes platforms

​Installation steps

​Docker Compose (multi-node)

​Next steps

Quick start

Core features

Production deployment

Build an app

​Common issues

​Upgrading YugabyteDB

Build docs developers (and LLMs) love

Choose your platform

Prerequisites by platform

Operating system

System requirements

Software dependencies

System configuration

Operating system

System requirements

Software dependencies

Docker requirements

Resource allocation

Kubernetes requirements

Resource requirements per node

Supported Kubernetes platforms

Installation steps

Docker Compose (multi-node)

Next steps

Common issues

Upgrading YugabyteDB