macOS

RocksDB provides full support for macOS with optimized builds through Homebrew or manual compilation from source.

Prerequisites

System Requirements

macOS Version: OS X 10.9 (Mavericks) or later
Xcode Command Line Tools: Required for compilation
C++20 Support: Available in recent Xcode versions

Developer Tools

Install Xcode Command Line Tools:

xcode-select --install

Installation Methods

Option 1: Using Homebrew (Recommended)

The simplest way to install RocksDB on macOS:

Install Homebrew

If you haven’t installed Homebrew yet:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Xcode Command Line Tools

Even when using Homebrew, you need the command line tools:

xcode-select --install

Install RocksDB

brew install rocksdb

This installs RocksDB along with all required dependencies including compression libraries.

Verify installation

brew info rocksdb

Option 2: Building from Source

For custom builds or development work:

Install dependencies

Install required compression libraries:

brew install snappy lz4 zstd gflags

Clone repository

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

Build RocksDB

make static_lib

make shared_lib

make all

Don’t use make or make all for production builds. These compile in debug mode, which is significantly slower than release mode.

Run tests (optional)

make check

Compiler Requirements

RocksDB requires C++20 support:

Clang: Version 10 or higher (included in recent Xcode)
GCC: Version 11 or higher (can be installed via Homebrew)

Using GCC instead of Clang

If you prefer GCC over Clang:

brew install gcc
export CC=gcc-11
export CXX=g++-11
make static_lib

Build Options

Portable Build

By default, RocksDB optimizes for your specific Mac’s CPU. To build a binary compatible with different Macs:

PORTABLE=1 make static_lib

Universal Binary (Intel + Apple Silicon)

To build a universal binary that runs on both Intel and Apple Silicon Macs:

arch -arch x86_64 -arch arm64 make static_lib

Universal binary builds require Xcode 12 or later and may not support all optimization flags.

Apple Silicon (M1/M2/M3) Support

RocksDB fully supports Apple Silicon processors:

Native ARM64 Build

arch -arm64 make static_lib

Rosetta 2 (Intel Emulation)

arch -x86_64 make static_lib

Native ARM64 builds provide better performance on Apple Silicon. Only use Rosetta 2 for compatibility with existing Intel-only dependencies.

Development Setup

Installing Additional Tools

For RocksDB development on macOS:

# Install build tools
brew install cmake ninja

# Install code formatting tools
brew install clang-format

# Install benchmarking tools (optional)
git clone --depth 1 --branch v1.7.0 https://github.com/google/benchmark.git ~/benchmark
cd ~/benchmark && mkdir build && cd build
cmake .. -GNinja -DCMAKE_BUILD_TYPE=Release -DBENCHMARK_ENABLE_GTEST_TESTS=0
ninja && ninja install

Xcode Project Generation

Generate an Xcode project for IDE development:

mkdir build
cd build
cmake -G Xcode ..

Open the generated .xcodeproj file in Xcode.

Configuration for macOS

Compression Libraries

RocksDB links with the following compression libraries on macOS:

zlib: Included with macOS
snappy: Install via Homebrew
lz4: Install via Homebrew
zstandard: Install via Homebrew
bzip2: Included with macOS

Verify installed compression libraries:

brew list | grep -E 'snappy|lz4|zstd'

Environment Variables

For custom library paths:

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

Performance Optimization

Recommended Build Flags

For production builds on macOS:

DEBUG_LEVEL=0 make static_lib

Thread Pool Configuration

macOS uses Grand Central Dispatch (GCD), but RocksDB uses std::thread for consistency:

rocksdb::Options options;
options.IncreaseParallelism();  // Optimizes for your Mac's CPU count

Troubleshooting

Command Line Tools not found

Ensure Xcode Command Line Tools are installed:

xcode-select --install

If already installed, reset the path:

sudo xcode-select --reset

Compression library linking errors

Install missing libraries via Homebrew:

brew install snappy lz4 zstd

Ensure Homebrew’s library path is in your environment:

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

C++20 compilation errors

Update Xcode to the latest version:

# Update Xcode through App Store
# Then update command line tools
sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

Apple Silicon compatibility issues

Ensure you’re building for the correct architecture:

# Check current architecture
arch

# Build for native architecture
make clean
make static_lib

Verification

Verify your RocksDB installation:

# Check library was built
ls -lh librocksdb.a

# Run tests
make check

# Check library dependencies
otool -L librocksdb.dylib  # For shared library

Next Steps

Getting Started

Learn the basics of using RocksDB

API Reference

Explore the complete API documentation

Configuration

Optimize RocksDB for your workload

Performance

Benchmark and tune performance

Community

Platform Support

Prerequisites

System Requirements

Developer Tools

Installation Methods

Option 1: Using Homebrew (Recommended)

Option 2: Building from Source

Compiler Requirements

Using GCC instead of Clang

Build Options

Portable Build

Universal Binary (Intel + Apple Silicon)

Apple Silicon (M1/M2/M3) Support

Native ARM64 Build

Rosetta 2 (Intel Emulation)

Development Setup

Installing Additional Tools

Xcode Project Generation

Configuration for macOS

Compression Libraries

Environment Variables

Performance Optimization

Recommended Build Flags

Thread Pool Configuration

Troubleshooting

Verification

Next Steps

Getting Started

API Reference

Configuration

Performance

​Prerequisites

​System Requirements

​Developer Tools

​Installation Methods

​Option 1: Using Homebrew (Recommended)

​Option 2: Building from Source

​Compiler Requirements

​Using GCC instead of Clang

​Build Options

​Portable Build

​Universal Binary (Intel + Apple Silicon)

​Apple Silicon (M1/M2/M3) Support

​Native ARM64 Build

​Rosetta 2 (Intel Emulation)

​Development Setup

​Installing Additional Tools

​Xcode Project Generation

​Configuration for macOS

​Compression Libraries

​Environment Variables

​Performance Optimization

​Recommended Build Flags

​Thread Pool Configuration

​Troubleshooting

​Verification

​Next Steps

Getting Started

API Reference

Configuration

Performance

Prerequisites

System Requirements

Developer Tools

Installation Methods

Option 1: Using Homebrew (Recommended)

Option 2: Building from Source

Compiler Requirements

Using GCC instead of Clang

Build Options

Portable Build

Universal Binary (Intel + Apple Silicon)

Apple Silicon (M1/M2/M3) Support

Native ARM64 Build

Rosetta 2 (Intel Emulation)

Development Setup

Installing Additional Tools

Xcode Project Generation

Configuration for macOS

Compression Libraries

Environment Variables

Performance Optimization

Recommended Build Flags

Thread Pool Configuration

Troubleshooting

Verification

Next Steps