Installation

Install QuestDB using Docker, Homebrew, binaries, or build from source

Installation Guide

QuestDB can be installed using multiple methods depending on your environment and requirements. Choose the installation method that best fits your needs.

Docker (Recommended)

Docker provides the fastest and most convenient way to get started with QuestDB.

Basic Docker Setup

1. Pull the latest image

   docker pull questdb/questdb
   
2. Run QuestDB interactively

   docker run --rm -it -p 9000:9000 -p 9009:9009 -p 8812:8812 questdb/questdb
   

   The --rm flag removes the container when stopped. The -it flags run the container interactively.

Docker with Persistent Storage

For production use, mount a volume to persist data:

Linux/macOS

docker run --rm -it \
  -p 9000:9000 -p 9009:9009 -p 8812:8812 \
  -v "$HOME/questdb:/var/lib/questdb" \
  questdb/questdb

Named Container for Easy Management

Create a named container for easy start/stop operations:

1. Create the container

   docker create --name questdb \
     -p 9000:9000 -p 9009:9009 -p 8812:8812 \
     -v "$HOME/questdb:/var/lib/questdb" \
     questdb/questdb
   
2. Manage the container

   # Start QuestDB
   docker start questdb
   
   # Stop QuestDB
   docker stop questdb
   
   # View logs
   docker logs questdb
   
   # Follow logs in real-time
   docker logs -f questdb
   

QuestDB stores data in /var/lib/questdb inside the container. Mount this directory to your host system to persist data across container restarts.

Homebrew (macOS)

macOS users can install QuestDB using Homebrew for a native experience.

1. Install QuestDB

   brew install questdb
   
2. Start QuestDB as a service

   brew services start questdb
   

   This starts QuestDB in the background and configures it to start automatically on system boot.

3. Or run QuestDB manually

   questdb start
   

   To stop:

   questdb stop
   

When installed via Homebrew, QuestDB stores data in /usr/local/var/questdb by default.

Binary Installation

Download pre-built binaries for direct installation on Linux, macOS, or Windows.

1. Download the binary

   Visit the QuestDB releases page and download the appropriate binary for your platform:

   • questdb-<version>-rt-linux-amd64.tar.gz for Linux
   • questdb-<version>-rt-darwin-amd64.tar.gz for macOS
   • questdb-<version>-rt-windows-amd64.zip for Windows
2. Extract the archive

   Linux/macOS

   tar -xvf questdb-<version>-rt-linux-amd64.tar.gz
   cd questdb-<version>-rt-linux-amd64
   
3. Run QuestDB

   Linux/macOS

   # Create a data directory
   mkdir ~/questdb-data
   
   # Start QuestDB
   ./questdb.sh start -d ~/questdb-data
   

Building from Source

For contributors and advanced users who want to build QuestDB from source.

Prerequisites

• Java 11 64-bit or higher
• Maven 3
• Git

1. Clone the repository

   git clone https://github.com/questdb/questdb.git
   cd questdb
   
2. Build the JAR

   Without Web Console (faster)

   mvn clean package -DskipTests
   

   Building with the web console and binaries takes longer but provides a complete distribution.

3. Run QuestDB

   # Create a data directory
   mkdir ~/questdb-data
   
   # Run from JAR
   java -p core/target/questdb-<version>-SNAPSHOT.jar \
     -m io.questdb/io.questdb.ServerMain \
     -d ~/questdb-data
   

   The web console will be available at http://localhost:9000

Building Native C/C++ Libraries

QuestDB uses native C/C++ libraries for performance-critical operations. To rebuild these:

1. Install build tools

   • Linux: gcc, g++, cmake
   • macOS: Xcode Command Line Tools, cmake
   • Windows: Visual Studio with C++ tools, cmake
2. Build native libraries

   cd core
   cmake -B build/release -DCMAKE_BUILD_TYPE=Release
   cmake --build build/release --config Release
   

   Native libraries are automatically placed in core/src/main/resources/io/questdb/bin/

Verifying Your Installation

After installation, verify QuestDB is running correctly:

1. Check the web console

   Open http://localhost:9000 in your browser. You should see the QuestDB Web Console.

2. Test the REST API

   curl http://localhost:9000/exec?query=SELECT%20version()
   

   You should receive a JSON response with the QuestDB version.

3. Test PostgreSQL wire protocol

   psql -h localhost -p 8812 -U admin -d qdb
   

   The default database is qdb with user admin and password quest.

Port Reference

QuestDB uses the following default ports:

Port	Protocol	Description
9000	HTTP	Web Console and REST API
9009	TCP	InfluxDB Line Protocol (ILP) for high-performance ingestion
8812	TCP	PostgreSQL wire protocol for programmatic queries

Ensure these ports are available before starting QuestDB. If you need to use different ports, see the Configuration guide for details on port customization.

Next Steps

Quick Start

Run your first queries and explore QuestDB’s features

Configuration

Configure QuestDB for production workloads

Ingestion

Learn about data ingestion methods

Deployment

Deploy QuestDB to AWS, GCP, or Kubernetes

Troubleshooting

Port Already in Use

If you see an error about ports already in use:

# Check what's using a port (Linux/macOS)
lsof -i :9000

# Windows
netstat -ano | findstr :9000

Either stop the conflicting service or configure QuestDB to use different ports.

Docker Permission Errors

If you encounter permission errors when mounting volumes on Linux:

# Run with user ID mapping
docker run --rm -it \
  --user $(id -u):$(id -g) \
  -p 9000:9000 -p 9009:9009 -p 8812:8812 \
  -v "$HOME/questdb:/var/lib/questdb" \
  questdb/questdb

Java Version Issues

Ensure you’re using Java 11 or higher:

java --version

If you have multiple Java versions, set JAVA_HOME to point to Java 11+:

export JAVA_HOME=/path/to/java11