The DuckDB Python package has its own repository at duckdb/duckdb-python and uses pybind11 to create Python bindings with DuckDB.
Prerequisites
This guide assumes:
- You have a working copy of the DuckDB Python package source (including git submodules and tags)
- You have Astral UV version >= 0.8.0 installed
- You run commands from the root of the duckdb-python source
We are opinionated about using Astral UV for Python environment and dependency management. While using pip for a development environment with an editable install without build isolation is possible, we don't provide guidance for that approach in this guide.
We use CLion as our IDE. This guide doesn't include specific instructions for other IDEs, but the setup should be similar.
1. DuckDB Python Repository
Start by forking duckdb-python into a personal repository, then clone your fork:
git clone --recurse-submodules [YOUR_FORK_URL]
cd duckdb-python
git remote add upstream https://github.com/duckdb/duckdb-python.git
git fetch --all
If you've already cloned without submodules:
git submodule update --init --recursive
git remote add upstream https://github.com/duckdb/duckdb-python.git
git fetch --all
Important notes:
- DuckDB is vendored as a git submodule and must be initialized
- DuckDB version determination depends on local availability of git tags
- If switching between branches with different submodule refs, add the git hooks:
git config --local core.hooksPath .githooks/
2. Install Astral uv
Install uv version >= 0.8.0.
Development Environment Setup
1. Platform-Specific Setup
All Platforms:
- Python 3.9+ supported
- uv >= 0.8.0 required
- CMake and Ninja (installed via UV)
- C++ compiler toolchain
Linux (Ubuntu 24.04):
sudo apt-get update
sudo apt-get install ccache
macOS:
# Xcode command line tools
xcode-select --install
Windows:
- Visual Studio 2019+ with C++ support
- Git for Windows
2. Install Dependencies and Build
Set up the development environment in two steps:
# Install all development dependencies without building the project
uv sync --no-install-project
# Build and install the project without build isolation
uv sync --no-build-isolation
Why two steps?
uv sync
performs editable installs by default with scikit-build-core using a persistent build-dir- The build happens in an isolated, ephemeral environment where cmake's paths point to non-existing directories
- Installing dependencies first, then building without isolation ensures proper cmake integration
3. Enable Pre-Commit Hooks
We run a number of linting, formatting and type-checking in CI. You can run all of these manually, but to make your life easier you can install the exact same checks we run in CI as git hooks with pre-commit, which is already installed as part of the dev dependencies:
uvx pre-commit install
This will run all required checks before letting your commit pass.
You can also install a post-checkout hook that always runs git submodule update --init --recursive
. When you change branches between main and a bugfix branch, this makes sure the duckdb submodule is always correctly initialized:
uvx pre-commit install --hook-type post-checkout
4. Verify Installation
uv run python -c "import duckdb; print(duckdb.sql('SELECT 42').fetchall())"
Development Workflow
Running Tests
Run all tests:
uv run --no-build-isolation pytest ./tests --verbose
Run fast tests only (excludes slow directory):
uv run --no-build-isolation pytest ./tests --verbose --ignore=./tests/slow
Test Coverage
Run with coverage (compiles extension with --coverage
for C++ coverage):
COVERAGE=1 uv run --no-build-isolation coverage run -m pytest ./tests --verbose
Check Python coverage:
uv run coverage html -d htmlcov-python
uv run coverage report --format=markdown
Check C++ coverage:
uv run gcovr \
--gcov-ignore-errors all \
--root "$PWD" \
--filter "${PWD}/src/duckdb_py" \
--exclude '.*/\.cache/.*' \
--gcov-exclude '.*/\.cache/.*' \
--gcov-exclude '.*/external/.*' \
--gcov-exclude '.*/site-packages/.*' \
--exclude-unreachable-branches \
--exclude-throw-branches \
--html --html-details -o coverage-cpp.html \
build/coverage/src/duckdb_py \
--print-summary
Building Wheels
Build wheel for your system:
uv build
Build for specific Python version:
uv build -p 3.9
Cleaning Build Artifacts
uv cache clean
rm -rf build .venv uv.lock
IDE Setup (CLion)
For CLion users, the project can be configured for C++ debugging of the Python extension:
CMake Profile Configuration
In Settings → Build, Execution, Deployment → CMake, create a Debug profile:
- Name: Debug
- Build type: Debug
- Generator: Ninja
- CMake Options:
-DCMAKE_PREFIX_PATH=$CMakeProjectDir$/.venv;$CMAKE_PREFIX_PATH
Python Debug Configuration
Create a CMake Application run configuration:
- Name: Python Debug
- Target:
All targets
- Executable:
[PROJECT_DIR]/.venv/bin/python3
- Program arguments:
$FilePath$
- Working directory:
$ProjectFileDir$
This allows setting C++ breakpoints and debugging Python scripts that use the DuckDB extension.
Debugging
Command Line Debugging
Set breakpoints and debug with lldb:
# Example Python script (test.py)
# import duckdb
# print(duckdb.sql("select * from range(1000)").df())
lldb -- .venv/bin/python3 test.py
In lldb:
# Set breakpoint (library loads when imported)
(lldb) br s -n duckdb::DuckDBPyRelation::FetchDF
(lldb) r
Cross-Platform Testing
You can run the packaging workflow manually on your fork for any branch, choosing platforms and test suites via the GitHub Actions web interface.
Troubleshooting
Build Issues
Missing git tags: If you forked DuckDB Python, ensure you have the upstream tags:
git remote add upstream https://github.com/duckdb/duckdb-python.git
git fetch --tags upstream
git push --tags
Platform-Specific Issues
Windows compilation: Ensure you have Visual Studio 2019+ with C++ support installed.