Installation Guide

Overview

This guide covers installing RocksDB on various platforms. RocksDB can be compiled from source or installed via package managers on supported platforms.

Important: If you plan to run RocksDB in production, don’t compile using default make or make all. These compile RocksDB in debug mode, which is much slower than release mode.

Quick Install

brew install rocksdb

Requirements

RocksDB requires modern C++ compiler support:

GCC >= 11 (for C++20 support)
Clang >= 10 (for C++20 support)
MSVC 2017 or later (Windows)

Building from Source

Linux (Ubuntu/Debian)

Install Dependencies

Install required development tools and compression libraries:

# Upgrade GCC to version 11 or later
sudo apt-get update
sudo apt-get install build-essential

# Install compression libraries (recommended)
sudo apt-get install libsnappy-dev
sudo apt-get install zlib1g-dev
sudo apt-get install libbz2-dev
sudo apt-get install liblz4-dev
sudo apt-get install libzstd-dev

# Install gflags (optional, needed for tools)
sudo apt-get install libgflags-dev

Compression libraries are optional but highly recommended. RocksDB can compile without them, but you’ll have fewer compression options.

Clone the Repository

git clone https://github.com/facebook/rocksdb.git
cd rocksdb

Build Static Library (Recommended)

Build the release version for production use:

make static_lib

This compiles librocksdb.a in release mode with optimizations enabled.

Performance: By default, the binary is optimized for the CPU you’re compiling on (-march=native). For a more portable binary, use PORTABLE=1 make static_lib.

Build Shared Library (Optional)

If you need a shared library:

make shared_lib

This creates librocksdb.so.

Install (Optional)

Install system-wide:

sudo make install-static
# or for shared library
sudo make install-shared

Linux (CentOS/RHEL)

Install Dependencies

# Upgrade GCC to version 11 or later for C++20 support
sudo yum install gcc gcc-c++

# Install compression libraries
sudo yum install snappy snappy-devel
sudo yum install zlib zlib-devel
sudo yum install bzip2 bzip2-devel
sudo yum install lz4-devel
sudo yum install libzstd-devel

For gflags:

git clone https://github.com/gflags/gflags.git
cd gflags
git checkout v2.2.0
./configure && make && sudo make install

Add gflags to your environment:

export CPATH=/usr/local/include:$CPATH
export LIBRARY_PATH=/usr/local/lib:$LIBRARY_PATH

Build RocksDB

git clone https://github.com/facebook/rocksdb.git
cd rocksdb
make static_lib

macOS

Install Xcode Command Line Tools

xcode-select --install

Install via Homebrew (Easiest)

brew install rocksdb

This installs RocksDB and all dependencies.

Or Build from Source

# Install dependencies
brew install snappy lz4 zstd

# Clone and build
git clone https://github.com/facebook/rocksdb.git
cd rocksdb
make static_lib

Windows

Using vcpkg (Recommended)
Using CMake

Install vcpkg

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

Install RocksDB

.\vcpkg install rocksdb:x64-windows

Integrate with Visual Studio

.\vcpkg integrate install

Install Visual Studio

Install Visual Studio 2017 or later with C++ support.

Clone Repository

git clone https://github.com/facebook/rocksdb.git
cd rocksdb

Build with CMake

mkdir build
cd build
cmake -G "Visual Studio 16 2019" -A x64 ..
cmake --build . --config Release

Read CMakeLists.txt in the repository for detailed Windows build instructions.

FreeBSD

Install via Ports (Easiest)

cd /usr/ports/databases/rocksdb && make install

Or Build from Source

Install dependencies:

export BATCH=YES
cd /usr/ports/devel/gmake && make install
cd /usr/ports/devel/gflags && make install
cd /usr/ports/archivers/snappy && make install
cd /usr/ports/archivers/bzip2 && make install
cd /usr/ports/archivers/liblz4 && make install
cd /usr/ports/archivers/zstd && make install
cd /usr/ports/devel/git && make install

Build RocksDB:

git clone https://github.com/facebook/rocksdb.git
cd rocksdb
gmake static_lib

OpenBSD

Install Dependencies

pkg_add gmake gflags snappy bzip2 lz4 zstd git bash findutils gnuwatch

Build RocksDB

git clone https://github.com/facebook/rocksdb.git
cd rocksdb
gmake static_lib

Build Options

Compilation Targets

make static_lib

Recommended for production

Compiles librocksdb.a static library in release mode with optimizations

make shared_lib

Shared library

Compiles librocksdb.so shared library in release mode

make check

Testing

Compiles and runs all unit tests in debug mode (slow, for development only)

make all

Debug build

Compiles static library, tools, and tests in debug mode (not for production!)

Build Variables

# Build binary compatible with most CPUs (slower performance)
PORTABLE=1 make static_lib

Architecture Optimization: By default, RocksDB uses -march=native which creates a binary optimized for your CPU but may not work on other machines. Use PORTABLE=1 for wider compatibility.

Compression Libraries

RocksDB supports multiple compression algorithms:

Snappy

Fast compression with reasonable ratio

Ubuntu/Debian

sudo apt-get install libsnappy-dev

CentOS/RHEL

sudo yum install snappy snappy-devel

Best for: Low CPU overhead, good default choice

LZ4

Extremely fast compression

Ubuntu/Debian

sudo apt-get install liblz4-dev

CentOS/RHEL

sudo yum install lz4-devel

Best for: Maximum speed, minimal CPU usage

ZSTD (Zstandard)

Best compression ratio with good speed

Ubuntu/Debian

sudo apt-get install libzstd-dev

CentOS/RHEL

sudo yum install libzstd-devel

Best for: Balance of speed and compression ratio (recommended)

Zlib

Standard compression

Ubuntu/Debian

sudo apt-get install zlib1g-dev

CentOS/RHEL

sudo yum install zlib zlib-devel

Best for: Wide compatibility

Bzip2

High compression ratio, slower

Ubuntu/Debian

sudo apt-get install libbz2-dev

CentOS/RHEL

sudo yum install bzip2 bzip2-devel

Best for: Archival, cold storage

Verifying Installation

After installation, verify RocksDB works:

test.cc

#include <iostream>
#include "rocksdb/db.h"

int main() {
  std::cout << "RocksDB Version: " 
            << ROCKSDB_MAJOR << "."
            << ROCKSDB_MINOR << "."
            << ROCKSDB_PATCH << std::endl;
  return 0;
}

Compile and run:

g++ -std=c++20 test.cc -o test -lrocksdb
./test

Platform-Specific Notes

iOS

TARGET_OS=IOS make static_lib

When building projects using RocksDB iOS library, define the preprocessor macro: IOS_CROSS_COMPILE

AIX 6.1

export PORTABLE=1
export CC=gcc
export AR="ar -X64"
export EXTRA_ARFLAGS=-X64
export EXTRA_CFLAGS=-maix64
export EXTRA_CXXFLAGS=-maix64
export PLATFORM_LDFLAGS="-static-libstdc++ -static-libgcc"
export LIBPATH=/opt/freeware/lib
export JAVA_HOME=/usr/java8_64
export PATH=/opt/freeware/bin:$PATH

make static_lib

Solaris Sparc

export CC=gcc
export EXTRA_CFLAGS=-m64
export EXTRA_CXXFLAGS=-m64
export EXTRA_LDFLAGS=-m64
export PORTABLE=1
export PLATFORM_LDFLAGS="-static-libstdc++ -static-libgcc"

make static_lib

Troubleshooting

Compiler Version Too Old

Error: error: #error This file requires compiler and library support for the ISO C++ 2020 standardSolution: Upgrade to GCC 11+ or Clang 10+

Ubuntu

sudo apt-get install gcc-11 g++-11
export CC=gcc-11
export CXX=g++-11

Missing Compression Libraries

Error: Build succeeds but compression options don’t workSolution: Install compression libraries before building RocksDB. If you’ve already built RocksDB, clean and rebuild:

make clean
# Install missing compression libraries
sudo apt-get install libsnappy-dev liblz4-dev libzstd-dev
make static_lib

Link Errors

Error: undefined reference to rocksdb::...Solution: Make sure to link all required libraries:

g++ program.cc -o program -lrocksdb -lpthread -lsnappy -lz -lbz2 -llz4 -lzstd

Performance Issues

Issue: RocksDB runs very slowlySolution: You likely built in debug mode. Rebuild in release mode:

make clean
DEBUG_LEVEL=0 make static_lib

Next Steps

Quick Start

Build your first RocksDB application

API Reference

Explore the complete API

Configuration

Learn about RocksDB options and tuning

Examples

See real-world code examples

Get Started

Core Concepts

Developer Guide

Advanced Topics

Language Bindings

Tools & Utilities

Installation Guide

Overview

Quick Install

Requirements

Building from Source

Linux (Ubuntu/Debian)

Linux (CentOS/RHEL)

macOS

Windows

FreeBSD

OpenBSD

Build Options

Compilation Targets

Build Variables

Compression Libraries

Verifying Installation

Platform-Specific Notes

iOS

AIX 6.1

Solaris Sparc

Troubleshooting

Next Steps

Quick Start

API Reference

Configuration

Examples

Build docs developers (and LLMs) love

Get Started

Core Concepts

Developer Guide

Advanced Topics

Language Bindings

Tools & Utilities

​Overview

​Quick Install

​Requirements

​Building from Source

​Linux (Ubuntu/Debian)

​Linux (CentOS/RHEL)

​macOS

​Windows

​FreeBSD

​OpenBSD

​Build Options

​Compilation Targets

​Build Variables

​Compression Libraries

​Verifying Installation

​Platform-Specific Notes

​iOS

​AIX 6.1

​Solaris Sparc

​Troubleshooting

​Next Steps

Quick Start

API Reference

Configuration

Examples

Build docs developers (and LLMs) love

Overview

Quick Install

Requirements

Building from Source

Linux (Ubuntu/Debian)

Linux (CentOS/RHEL)

macOS

Windows

FreeBSD

OpenBSD

Build Options

Compilation Targets

Build Variables

Compression Libraries

Verifying Installation

Platform-Specific Notes

iOS

AIX 6.1

Solaris Sparc

Troubleshooting

Next Steps