Embedded CPython UDFs for DuckDB — py_eval, py_agg, py_scan, py_register, py_call, py_map
Maintainer(s):
alitrack
Compatibility Matrix
This table covers all DuckDB releases that have not reached end-of-life, including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.
| Platform | 1.4.4 | 1.4.5 | 1.5.5 | 1.5.6 | 2.0.0 |
|---|---|---|---|---|---|
| Linux AMD64 | |||||
| Linux ARM64 | |||||
| macOS AMD64 | |||||
| macOS ARM64 | |||||
| Windows AMD64 | |||||
| Windows ARM64 | |||||
| WebAssembly |
Installing and Loading
INSTALL python_udf FROM community;
LOAD python_udf;
Example
LOAD python_udf;
SELECT py_eval('lambda x: x * 2 + 1', x) FROM range(10) t(x);
-- Aggregate UDF
SELECT py_agg('sum', x) FROM range(100) t(x);
-- Scan from Python
SELECT * FROM py_scan('lambda _: [{"a":1}, {"a":2}]');
-- Register persistent UDF
SELECT py_register('dbl', 'lambda x: x * 2');
-- Call registered UDF
SELECT py_call('dbl', 21);
-- Map values
SELECT py_map('ord', 'hello world');
About python_udf
CPython UDFs for DuckDB
Execute Python code directly in SQL queries with CPython embedded in DuckDB.
7 Functions:
| Function | Type | Description |
|---|---|---|
py_eval(name, arg..) |
Scalar | Evaluate Python lambda/function per row |
py_agg(name, arg) |
Aggregate | Full-table aggregate UDF |
py_scan(func) |
Table | Generate rows from Python |
py_register(name, func) |
Management | Register a Python UDF |
py_call(name, arg..) |
Scalar | Call a registered UDF |
py_map(func, arg..) |
Scalar | Map a function over values |
py_list(name) |
Utility | List registered UDFs |
Design:
- CPython embedded via PyO3 (Rust FFI)
- Fresh Python interpreter per DuckDB connection
- Supports Python 3.11, 3.12, 3.13
- macOS, Linux x64 supported
Note: Extension binary name is python_udf to avoid collision
with DuckDB's core python extension.
The source repository remains duckdb-python.
Added Functions
This extension does not add any functions.
Overloaded Functions
This extension does not add any function overloads.
Added Types
This extension does not add any types.
Added Settings
This extension does not add any settings.