Installation

Install DuckDB as a CLI tool or embed it in your application using various programming languages.

Installation

DuckDB can be used as a standalone CLI application or embedded directly into your application. This guide covers building from source and using the embedded C/C++ libraries.

For pre-built binaries and client libraries for Python, R, Java, and other languages, visit the official installation page.

Building from Source

To build DuckDB from source, you’ll need:

• CMake (3.5 or higher)
• Python 3
• A C++11 compliant compiler (GCC, Clang, or MSVC)

Build Steps

1. Clone the repository

   git clone https://github.com/duckdb/duckdb.git
   cd duckdb
   
2. Build the release version

   For a production-ready optimized build:

   make
   

   This creates the DuckDB CLI and libraries in build/release/.

3. Build for development (optional)

   For development with debug symbols and no optimizations:

   make debug
   

   This creates a debug build in build/debug/.

4. Verify the build

   Run unit tests to ensure everything works:

   make unit        # Fast unit tests (~1 minute)
   make allunit     # All unit tests (~1 hour)
   

Build Performance Tips

Use Ninja

Speed up builds with the Ninja build system:

GEN=ninja make

Use ccache

Install ccache to speed up rebuilds:

# The build system auto-detects ccache
sudo apt install ccache  # Ubuntu/Debian
brew install ccache      # macOS

Parallel Builds

Control the number of parallel build processes to avoid system lockup:

# Limit to 4 parallel processes
CMAKE_BUILD_PARALLEL_LEVEL=4 GEN=ninja make

# Use all available cores
CMAKE_BUILD_PARALLEL_LEVEL=$(nproc) make

Using the CLI

After building, the DuckDB CLI is available at:

./build/release/duckdb

Launch it to start an interactive SQL session:

$ ./build/release/duckdb
v1.0.0
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.

D SELECT 'Hello, DuckDB!' as message;
┌─────────────────┐
│     message     │
│     varchar     │
├─────────────────┤
│ Hello, DuckDB!  │
└─────────────────┘

The CLI supports both in-memory databases and persistent file-based databases. Use .open mydb.db to create or open a database file.

Embedded Library Usage

DuckDB can be embedded directly into your C or C++ application.

C API

The C API provides a simple interface for embedding DuckDB:

#include "duckdb.h"
#include <stdio.h>

int main() {
    duckdb_database db = NULL;
    duckdb_connection con = NULL;
    
    // Open database (NULL = in-memory)
    if (duckdb_open(NULL, &db) == DuckDBError) {
        fprintf(stderr, "Failed to open database\n");
        return 1;
    }
    
    // Create connection
    if (duckdb_connect(db, &con) == DuckDBError) {
        fprintf(stderr, "Failed to connect\n");
        duckdb_close(&db);
        return 1;
    }
    
    // Your queries here
    
    // Cleanup
    duckdb_disconnect(&con);
    duckdb_close(&db);
    return 0;
}

C++ API

The C++ API provides a more ergonomic interface:

#include "duckdb.hpp"

using namespace duckdb;

int main() {
    // Open database (nullptr = in-memory)
    DuckDB db(nullptr);
    
    // Create connection
    Connection con(db);
    
    // Execute queries
    con.Query("CREATE TABLE integers(i INTEGER)");
    con.Query("INSERT INTO integers VALUES (42)");
    
    auto result = con.Query("SELECT * FROM integers");
    result->Print();
    
    return 0;
}

Linking Against DuckDB

After building DuckDB, link your application against the library:

# C example
gcc myapp.c -o myapp -I/path/to/duckdb/src/include \
    -L/path/to/duckdb/build/release/src -lduckdb

# C++ example
g++ myapp.cpp -o myapp -I/path/to/duckdb/src/include \
    -L/path/to/duckdb/build/release/src -lduckdb -std=c++11

Make sure to set LD_LIBRARY_PATH or equivalent to include the DuckDB library directory when running your application.

Client Libraries

For most use cases, you’ll want to use a pre-built client library:

Python

pip install duckdb

R

install.packages("duckdb")

Java

Maven/Gradle dependency available

Node.js

npm install duckdb

Next Steps

Now that you have DuckDB installed, head over to the Quick Start guide to run your first queries and learn the basics.