Quick start guide

Get your first YugabyteDB cluster up and running in under 5 minutes. This guide walks you through installation, cluster creation, and running your first SQL queries.

Prerequisites

Before you begin, ensure your system meets the following requirements:

Linux
macOS
Docker

Operating system

CentOS 7 or later
Ubuntu 18.04 or later
Red Hat Enterprise Linux (RHEL) 7 or later

Software

Python 3.6 or later
wget or curl

Hardware

2 CPU cores (4 recommended)
4 GB RAM minimum (8 GB recommended)
10 GB disk space

Step 1: Download YugabyteDB

Download the latest stable release of YugabyteDB:

Linux (x86)
Linux (ARM)
macOS
Docker

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

# Verify checksum
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

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

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

# Verify checksum
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

# Extract
tar xvfz yugabyte-2025.2.0.0-b2-el8-aarch64.tar.gz
cd yugabyte-2025.2.0.0/

# Download for your architecture
wget https://downloads.yugabyte.com/releases/2025.2.0.0/yugabyte-2025.2.0.0-b2-darwin-x86_64.tar.gz

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

# Pull the latest image
docker pull yugabytedb/yugabyte:2025.2.0.0-b2

For the latest version numbers and download links, visit the YugabyteDB releases page.

Step 2: Configure YugabyteDB

Linux / macOS
Docker

Run the post-installation script to configure YugabyteDB:

./bin/post_install.sh

This script:

Sets up the necessary directory structure
Configures system libraries
Prepares the environment for running YugabyteDB

Step 3: Start a local cluster

Create a single-node cluster for local development:

Linux / macOS
Docker

./bin/yugabyted start --advertise_address=127.0.0.1

You’ll see output like:

Starting yugabyted...
✓ System checks
✓ Creating cluster
✓ Starting master service
✓ Starting tserver service
✓ Waiting for services to be ready

YugabyteDB started successfully!

UI:   http://127.0.0.1:15433
YSQL: bin/ysqlsh -h 127.0.0.1
YCQL: bin/ycqlsh 127.0.0.1

On macOS Monterey or later, if port 7000 is in use by AirPlay, use -p 7001:7000 to forward to a different port.

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

Check the container status:

docker ps

Verify the cluster is running:

docker exec -it yugabyte yugabyted status

The yugabyted utility is a single command to create and manage local clusters. It automatically starts both YB-Master (metadata manager) and YB-TServer (data server) processes.

Step 4: Verify the cluster

Check that your cluster is running:

Linux / macOS
Docker

./bin/yugabyted status

Expected output:

+----------------------------------------------------------------------------------------------------------+
|                                                yugabyted                                                 |
+----------------------------------------------------------------------------------------------------------+
| Status              : Running                                                                            |
| Replication Factor  : 1                                                                                  |
| YugabyteDB UI       : http://127.0.0.1:15433                                                            |
| JDBC                : jdbc:postgresql://127.0.0.1:5433/yugabyte?user=yugabyte&password=yugabyte        |
| YSQL                : bin/ysqlsh -h 127.0.0.1 -U yugabyte -d yugabyte                                   |
| YCQL                : bin/ycqlsh 127.0.0.1 9042 -u cassandra                                            |
| Data Dir            : /home/user/var/data                                                               |
| Log Dir             : /home/user/var/logs                                                               |
| Universe UUID       : 550e8400-e29b-41d4-a716-446655440000                                              |
+----------------------------------------------------------------------------------------------------------+

docker exec -it yugabyte yugabyted status

Step 5: Connect to the database

Connect using the YSQL shell (PostgreSQL-compatible interface):

Linux / macOS
Docker

./bin/ysqlsh -h 127.0.0.1

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

You should see the YSQL prompt:

ysqlsh (15.2-YB-2025.2.0.0-b0)
Type "help" for help.

yugabyte=#

Step 6: Run your first queries

Let’s create a simple table and insert some data:

Create a table

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100),
  email VARCHAR(100) UNIQUE,
  created_at TIMESTAMP DEFAULT NOW()
);

Insert data

INSERT INTO users (name, email) VALUES
  ('Alice Johnson', '[email protected]'),
  ('Bob Smith', '[email protected]'),
  ('Carol White', '[email protected]');

Query the data

SELECT * FROM users;

Expected output:

 id |     name      |       email        |         created_at
----+---------------+--------------------+----------------------------
  1 | Alice Johnson | [email protected]  | 2026-03-04 10:30:15.123456
  2 | Bob Smith     | [email protected]    | 2026-03-04 10:30:15.123456
  3 | Carol White   | [email protected]  | 2026-03-04 10:30:15.123456
(3 rows)

Try a transaction

BEGIN;
  UPDATE users SET name = 'Alice Smith' WHERE id = 1;
  UPDATE users SET email = '[email protected]' WHERE id = 1;
COMMIT;

SELECT * FROM users WHERE id = 1;

This demonstrates YugabyteDB’s ACID transaction support.

Step 7: Access the web UI

YugabyteDB includes a built-in web interface for monitoring and administration:

Open the UI

Navigate to http://127.0.0.1:15433 in your browser.

Explore the dashboard

The UI provides:

Cluster overview and health status
Performance metrics and charts
Node information and tablet distribution
Query statistics
Database tables and indexes

The web UI runs on port 15433 by default. No authentication is required for local development clusters.

What’s next?

Now that you have YugabyteDB running, explore more:

Build an application

Connect from Java, Python, Go, Node.js, or other languages

Core features

Learn about sharding, replication, and distributed transactions

Sample data

Load sample datasets to explore YugabyteDB features

Production deployment

Deploy a multi-node cluster for production use

Common commands

Here are some useful commands for managing your cluster:

./bin/yugabyted start --advertise_address=127.0.0.1

Troubleshooting

Port already in use

If you see “address already in use” errors:

Check what’s using the port: lsof -i :5433
Stop the conflicting service or use a different port
On macOS Monterey, disable AirPlay or use port forwarding

Cannot connect to cluster

If you can’t connect:

Verify the cluster is running: yugabyted status
Check firewall settings
Ensure you’re using the correct IP address (127.0.0.1 for local)
Review logs in ~/var/logs/ for errors

Performance issues

For slow queries:

Ensure you have adequate RAM (4 GB minimum)
Use SSDs for better I/O performance
Check CPU usage isn’t maxed out
Review query plans with EXPLAIN ANALYZE

Docker container won't start

If Docker fails:

Ensure Docker has enough resources allocated
Check Docker logs: docker logs yugabyte
Try removing and recreating: docker rm yugabyte
Verify port conflicts with docker ps

For more troubleshooting help, check the YugabyteDB documentation or ask in the community Slack.

Multi-node cluster (optional)

Want to test with multiple nodes? Here’s how to create a 3-node local cluster:

Start first node

./bin/yugabyted start --advertise_address=127.0.0.1 \
  --base_dir=/tmp/ybd1

Start second node

./bin/yugabyted start --advertise_address=127.0.0.2 \
  --base_dir=/tmp/ybd2 \
  --join=127.0.0.1

Start third node

./bin/yugabyted start --advertise_address=127.0.0.3 \
  --base_dir=/tmp/ybd3 \
  --join=127.0.0.1

Configure replication

./bin/yugabyted configure data_placement --fault_tolerance=zone \
  --base_dir=/tmp/ybd1

Multi-node local clusters require loopback alias configuration. See the deployment documentation for details.

Get Started

Core Concepts

Deployment

Develop

Operations

Security

Advanced Features

Prerequisites

Step 1: Download YugabyteDB

Step 2: Configure YugabyteDB

Step 3: Start a local cluster

Step 4: Verify the cluster

Step 5: Connect to the database

Step 6: Run your first queries

Step 7: Access the web UI

What’s next?

Build an application

Core features

Sample data

Production deployment

Common commands

Troubleshooting

Multi-node cluster (optional)

Build docs developers (and LLMs) love

Get Started

Core Concepts

Deployment

Develop

Operations

Security

Advanced Features

​Prerequisites

​Step 1: Download YugabyteDB

​Step 2: Configure YugabyteDB

​Step 3: Start a local cluster

​Step 4: Verify the cluster

​Step 5: Connect to the database

​Step 6: Run your first queries

​Step 7: Access the web UI

​What’s next?

Build an application

Core features

Sample data

Production deployment

​Common commands

​Troubleshooting

​Multi-node cluster (optional)

Build docs developers (and LLMs) love

Prerequisites

Step 1: Download YugabyteDB

Step 2: Configure YugabyteDB

Step 3: Start a local cluster

Step 4: Verify the cluster

Step 5: Connect to the database

Step 6: Run your first queries

Step 7: Access the web UI

What’s next?

Common commands

Troubleshooting

Multi-node cluster (optional)