Install for Python

Python · Node · Go · Rust · Swift · Dart · JVM · .NET · C++ · Objective-C

See Concepts for the runtime, remote, and synchronization terms used on this page.

Requirements

Use Python 3.14 or newer on macOS, Linux, or Windows.

Install the package with this command.

pip install potluckdb

The wheel contains the runtime for your platform. Its potluckdb-storage dependency provides remotes for these storage services:

You need no other installation steps.

A remote is the shared copy of a database that devices synchronize with. The quickstart uses a directory as its remote.

To use a storage service, replace the directory constructor with a storage service constructor.

import potluckdb

remote = potluckdb.storage.from_s3("my-bucket", "notes", region="eu-west-1")
db = potluckdb.open("app.potluckdb", remote)

The rest of the program stays the same. The Google Cloud Storage and Azure Blob Storage constructors use the same form.

A credential chain tries the storage service’s standard sources for credentials. If you do not pass credentials, the constructor uses these sources:

For an S3-compatible storage service other than Amazon S3, such as Cloudflare R2, MinIO, Wasabi or IDrive e2, set endpoint to its address.

The storage reference gives each constructor’s signature and parameters, including endpoint, region, and force_path_style.

Analytical reads use DuckDB, a separate SQL engine for analysis. The core package does not contain DuckDB.

Install potluckdb-analytics with this command.

pip install potluckdb-analytics

The runtime loads the engine without further configuration.

Without a license key, potluckdb uses a trial. The licensing page explains the trial’s length and start, license key sources, and purchase steps.

Continue with the quickstart.