How to Install YugabyteDB Using Docker

May 08, 2025

YugabyteDB is a high-performance, distributed SQL database designed for cloud-native applications. It offers strong consistency, fault tolerance, and horizontal scalability, making it ideal for applications that demand high availability across multiple regions.
If you want to explore YugabyteDB locally—without installing it directly on your system—the fastest and easiest way is to run it using Docker. In this article, you’ll learn how to install YugabyteDB using Docker, step by step, and run a single-node cluster perfect for development and testing.

Why Use Docker for YugabyteDB?

Using Docker to run YugabyteDB offers several benefits:

No need to install or configure system packages
Quick to spin up and shut down
Isolated environment for safe testing
Consistent setup across machines and teams

Prerequisites

Before we begin, make sure Docker is installed and running on your machine.

For macOS or Windows:

Install Docker Desktop:
👉 https://www.docker.com/products/docker-desktop

For Ubuntu/Linux:

sudo apt update && sudo apt install docker.io

Check your Docker version:

docker --version

Step 1: Pull the YugabyteDB Docker Image

Open your terminal and pull the official YugabyteDB Docker image:

docker pull yugabytedb/yugabyte

You can also pull a specific version if needed, like:

docker pull yugabytedb/yugabyte:2.18.1.0-b15

Step 2: Run YugabyteDB in a Docker Container

Let’s start a single-node YugabyteDB cluster using the pulled image:

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

Explanation of ports:

7000: YB-Master Admin UI
9000: YB-TServer Admin UI
5433: PostgreSQL-compatible SQL API
9042: Cassandra-compatible YCQL API

Explanation of command:

--name yugabytedb: names the container
-d: runs in detached (background) mode
bin/yugabyted start --daemon=false: starts the cluster in foreground mode inside Docker

Step 3: Access YugabyteDB Admin UIs

Once the container is running, you can open your browser and access the admin dashboards.

Master Admin UI (Cluster status):

http://localhost:7000

TServer Admin UI (Tablet server info):

http://localhost:9000

These UIs give you insights into cluster status, node health, replication, and more.

Step 4: Connect Using PostgreSQL Clients

YugabyteDB supports a PostgreSQL-compatible API. You can connect using any Postgres client like psql, DBeaver, or DataGrip.

Using `psql`:

psql -h localhost -p 5433 -U yugabyte

Host: localhost
Port: 5433
User: yugabyte
Password: (default is empty—just press Enter if not prompted)

Once connected, you can run SQL commands like:

CREATE DATABASE testdb;
\c testdb
CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT);
INSERT INTO users (name) VALUES ('Alice');
SELECT * FROM users;

Step 5: Managing the Container

Here are some useful Docker commands to manage your YugabyteDB container:

Task	Command
Stop the container	`docker stop yugabytedb`
Start it again	`docker start yugabytedb`
Remove the container	`docker rm -f yugabytedb`
View logs	`docker logs yugabytedb`

Step 6: Persist Data Using Volumes (Optional)

By default, container data is removed when the container is deleted. To persist your YugabyteDB data:

Create a Docker volume:
```
docker volume create yb-data
```

Run the container with volume mounted:

docker run -d --name yugabytedb \
      -p 7000:7000 \
      -p 9000:9000 \
      -p 5433:5433 \
      -p 9042:9042 \
      -v yb-data:/home/yugabyte/var \
      yugabytedb/yugabyte \
      bin/yugabyted start --daemon=false

Now your data will persist even if the container is stopped or removed.

Best Practices

Use volumes to persist your data between container restarts.
Don’t expose ports publicly unless you're using a secure setup.
Use the PostgreSQL port 5433 for SQL clients and queries.
Use the Admin UI to monitor health and performance.