Python - Public Preview

The Python SDK is currently in Public Preview. If you encounter any issues or need assistance, please contact Ditto Support.

The Public Preview of the Ditto Python SDK can be used for exploratory development and prototypes. Refer to the documentation for supported features. Future versions of the Ditto Python SDK may not be compatible with the current preview API. The SDK is distributed on PyPI as dittolive-ditto and imported as ditto. It is an asyncio-native binding for Ditto’s v5 API.

Prerequisites

Python 3.10 – 3.13 (see Compatibility)
Linux (glibc 2.35 or later) on x86-64 or ARM64, or macOS 12 or later on Apple Silicon
A Ditto Portal account with a configured Ditto Database

Install the Python SDK

Create a project environment

We recommend uv, which installs and pins the Python interpreter along with your dependencies. The SDK is currently published as a preview (pre-release), so each command below enables pre-release installs.

uv init my-ditto-app
cd my-ditto-app
uv add --prerelease=allow dittolive-ditto

mkdir my-ditto-app
cd my-ditto-app
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --pre dittolive-ditto

poetry new my-ditto-app
cd my-ditto-app
poetry add dittolive-ditto --allow-prereleases

Verify the installation

python3 -c "from ditto import Ditto; print(Ditto.version())"

This imports the SDK, loads the native libdittoffi library, and prints the SDK version.

Then, in any Python source file that uses the Ditto SDK, import from the ditto package:

from ditto import Ditto, DittoConfig, DittoConfigConnect

Set the following environment variables with the values from the Ditto Portal:

export DITTO_DATABASE_ID=""
export DITTO_DEVELOPMENT_TOKEN=""
export DITTO_SERVER_URL=""

Python

import asyncio
import os
from datetime import timedelta

from ditto import AuthenticationProvider, Ditto, DittoConfig, DittoConfigConnect

DATABASE_ID = os.environ["DITTO_DATABASE_ID"]
DEVELOPMENT_TOKEN = os.environ["DITTO_DEVELOPMENT_TOKEN"]
SERVER_URL = os.environ["DITTO_SERVER_URL"]


async def main() -> None:
    config = DittoConfig(
        database_id=DATABASE_ID,
        connect=DittoConfigConnect.server(SERVER_URL),
        persistence_directory="./ditto-data",
    )

    async with Ditto.open(config) as ditto:
        async def on_expiration(peer: Ditto, time_until_expiration: timedelta) -> None:
            await peer.auth.login(DEVELOPMENT_TOKEN, AuthenticationProvider.DEVELOPMENT)

        ditto.auth.expiration_handler = on_expiration
        await ditto.auth.login(DEVELOPMENT_TOKEN, AuthenticationProvider.DEVELOPMENT)

        ditto.sync.start()


asyncio.run(main())

API documentation for the Python SDK can be found in the Python API Reference.

Native Library Setup

Unlike some other Ditto SDKs, you do not need to download the native library separately. Each prebuilt wheel bundles libdittoffi inside the package, and the SDK loads it automatically. Wheels are published for the following platforms:

Platform	Architecture	Wheel tag
Linux (glibc)	`x86_64`	`manylinux_2_35_x86_64`
Linux (glibc)	`aarch64`	`manylinux_2_35_aarch64`
macOS	`arm64` (Apple Silicon)	`macosx_12_0_arm64`

Use a Custom Native Library

For normal installations, no configuration is needed. The Ditto Python SDK loads the native library included in its installed wheel. If you are developing against a custom libdittoffi build, set DITTOFFI_LIB_PATH to the library file or the directory that contains it:

export DITTOFFI_LIB_PATH="/path/to/libdittoffi"

When opening Ditto, the SDK looks for the native library in this order:

DITTOFFI_LIB_PATH, if set.
The native library bundled with the installed dittolive-ditto package.
Directories in DITTOFFI_SEARCH_PATH.
A compatible build in a Ditto source checkout.
The operating system’s standard library locations.

Use DITTOFFI_LIB_PATH when you intentionally want to test or develop against a specific native-library build. Otherwise, leave these variables unset so the SDK uses the bundled library. To require the bundled library and exclude all custom-library fallbacks, set:

export DITTOFFI_REQUIRE_BUNDLED=1

Overview & Setup

SDKs

Accessing Data

Syncing Data

Authentication and Authorization

Managing the Mesh

Deploying your App

Python - Public Preview

Prerequisites

Install the Python SDK

Native Library Setup

Use a Custom Native Library

​Prerequisites

​Install the Python SDK

​Native Library Setup

​Use a Custom Native Library

Prerequisites

Install the Python SDK

Native Library Setup

Use a Custom Native Library