Vector Gateway Interface for Python
Extend DuckDB with functions written in Python — backed by Apache Arrow, callable straight from SQL.
Built for 
vgi-python implements the Vector Gateway Interface (VGI) for Python: you write a small worker exposing typed functions, and DuckDB calls them as if they were native. Data moves as Apache Arrow record batches, so it stays columnar and fast across the boundary — no row-by-row marshalling.
Function shapes
Section titled “Function shapes”VGI workers expose five function shapes — pick the one whose input/output cardinality matches your problem. Each links to a complete, runnable example in the function patterns guide.
Scalar1 row → 1 value
Tableargs → N rows
Table-in-outN rows → M rows
AggregateN rows → 1 value
Bufferingstream → [state] → streamStart here
Section titled “Start here”
Tutorial
Zero to a scalar and a table function callable from DuckDB, in about 20 minutes.
Function patterns
The five function shapes — scalar, table, table-in-out, aggregate, buffering — each with a complete, runnable worker.
How-to guides
Expose catalogs, persist state across workers, serve over HTTP with auth, and integrate with the optimizer.
API reference
The full Python API — functions, worker, catalogs, storage — generated from the source.
Install
Section titled “Install”# with uv
uv add vgi-python
# or with pip
pip install vgi-pythonThen follow the tutorial to build your first worker, or jump to the function patterns to find the shape that fits your problem.
Concepts & reference
Section titled “Concepts & reference”
Concepts
How a worker is bound, initialized, and invoked; how arguments are serialized.
CLI
Run and inspect workers with the vgi-serve command-line tool.
What's new
Everything that changed between 0.8 and 0.28 — result caching, COPY formats, global functions, and the two breaking changes.