README.md

February 22, 2026 · View on GitHub

DuckDB API for PHP

A wrapper over DuckDB C API

Caution

This project is in an early development stage and there are no plans to make it stable/production ready for now. Nevertheless, any contribution will be welcome. Check also satur-io/duckdb-php

Prerequisites

Install the DuckDB C library (libduckdb) into a standard system path before using PIE.

Linux

Official downloads: https://duckdb.org/install/?platform=linux&environment=c

x86_64 (amd64)

tmp="$(mktemp -d)"
curl -L "https://install.duckdb.org/v1.4.4/libduckdb-linux-amd64.zip" -o "$tmp/libduckdb.zip"
unzip -q "$tmp/libduckdb.zip" -d "$tmp"
sudo mkdir -p /usr/local/include /usr/local/lib
sudo install -m 644 "$tmp/duckdb.h" /usr/local/include/duckdb.h
sudo install -m 755 "$tmp/libduckdb.so" /usr/local/lib/libduckdb.so
sudo ldconfig

arm64 (aarch64)

tmp="$(mktemp -d)"
curl -L "https://install.duckdb.org/v1.4.4/libduckdb-linux-arm64.zip" -o "$tmp/libduckdb.zip"
unzip -q "$tmp/libduckdb.zip" -d "$tmp"
sudo mkdir -p /usr/local/include /usr/local/lib
sudo install -m 644 "$tmp/duckdb.h" /usr/local/include/duckdb.h
sudo install -m 755 "$tmp/libduckdb.so" /usr/local/lib/libduckdb.so
sudo ldconfig

macOS

Official downloads: https://duckdb.org/install/?platform=macos&environment=c

tmp="$(mktemp -d)"
curl -L "https://install.duckdb.org/v1.4.4/libduckdb-osx-universal.zip" -o "$tmp/libduckdb.zip"
unzip -q "$tmp/libduckdb.zip" -d "$tmp"
sudo mkdir -p /usr/local/include /usr/local/lib
sudo install -m 644 "$tmp/duckdb.h" /usr/local/include/duckdb.h
sudo install -m 755 "$tmp/libduckdb.dylib" /usr/local/lib/libduckdb.dylib

Windows

Official downloads: https://duckdb.org/install/?platform=windows&environment=c

Open PowerShell as Administrator.

x86_64 (amd64)

$vc = "$env:TEMP\vc_redist.x64.exe"
Invoke-WebRequest "https://aka.ms/vc14/vc_redist.x64.exe" -OutFile $vc
Start-Process -Wait -FilePath $vc -ArgumentList "/install","/passive","/norestart"

$version = "v1.4.4"
$zip = "libduckdb-windows-amd64.zip"
$dest = "$env:TEMP\duckdb"
New-Item -ItemType Directory -Force $dest | Out-Null
Invoke-WebRequest "https://install.duckdb.org/$version/$zip" -OutFile "$dest\libduckdb.zip"
Expand-Archive "$dest\libduckdb.zip" -DestinationPath $dest -Force
$target = "C:\Program Files\DuckDB"
New-Item -ItemType Directory -Force $target | Out-Null
Copy-Item "$dest\*" $target -Recurse -Force
$system = "C:\Windows"
Copy-Item "$dest\duckdb.dll" "$system\duckdb.dll" -Force
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$target", "User")
$env:Path += ";$target"

arm64

$vc = "$env:TEMP\vc_redist.arm64.exe"
Invoke-WebRequest "https://aka.ms/vc14/vc_redist.arm64.exe" -OutFile $vc
Start-Process -Wait -FilePath $vc -ArgumentList "/install","/passive","/norestart"

$version = "v1.4.4"
$zip = "libduckdb-windows-arm64.zip"
$dest = "$env:TEMP\duckdb"
New-Item -ItemType Directory -Force $dest | Out-Null
Invoke-WebRequest "https://install.duckdb.org/$version/$zip" -OutFile "$dest\libduckdb.zip"
Expand-Archive "$dest\libduckdb.zip" -DestinationPath $dest -Force
$target = "C:\Program Files\DuckDB"
New-Item -ItemType Directory -Force $target | Out-Null
Copy-Item "$dest\*" $target -Recurse -Force
$system = "C:\Windows"
Copy-Item "$dest\duckdb.dll" "$system\duckdb.dll" -Force
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$target", "User")
$env:Path += ";$target"

Installation (PIE)

PIE installs PHP extensions published on Packagist. Once this package is published, install it with:

pie install saturio/duckdb

If PIE cannot enable the extension automatically, add this to your INI:

extension=duckdb

Library in a non-standard path (advanced)

If you installed libduckdb outside the standard system paths, pass the prefix that contains include/duckdb.h and lib/libduckdb.*:

pie install saturio/duckdb --with-duckdb-dir=/path/to/duckdb

You can see available configure options with:

pie info saturio/duckdb

PIE lists the available configure options for an extension in pie info. Use those options with pie install.

If pie reports that --with-duckdb-dir does not exist, install a version that includes this option and confirm it appears in pie info before retrying.

As a fallback, you can also pass include and library paths via environment variables:

CPPFLAGS="-I/path/to/duckdb/include" LDFLAGS="-L/path/to/duckdb/lib" pie install saturio/duckdb