> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ditto.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Python - Public Preview

> You can integrate the Ditto SDK into Python projects to develop for Linux and macOS platforms.

<Callout icon="triangle-person-digging" color="#7C3AED" iconType="regular">
  The Python SDK is currently in **Public Preview**. If you encounter any issues or need assistance, please contact [Ditto Support](https://support.ditto.com).
</Callout>

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`](https://pypi.org/project/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](/sdk/latest/compatibility/python))
* Linux (glibc 2.35 or later) on x86-64 or ARM64, or macOS 12 or later on Apple Silicon
* A Ditto [Portal](https://portal.ditto.live) account with a configured Ditto Database

## Install the Python SDK

<Steps>
  <Step title="Create a project environment">
    We recommend [uv](https://docs.astral.sh/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.

    <CodeGroup>
      ```shell uv theme={null}
      uv init my-ditto-app
      cd my-ditto-app
      uv add --prerelease=allow dittolive-ditto
      ```

      ```shell pip theme={null}
      mkdir my-ditto-app
      cd my-ditto-app
      python3 -m venv .venv
      source .venv/bin/activate
      python3 -m pip install --pre dittolive-ditto
      ```

      ```shell poetry theme={null}
      poetry new my-ditto-app
      cd my-ditto-app
      poetry add dittolive-ditto --allow-prereleases
      ```
    </CodeGroup>
  </Step>

  <Step title="Verify the installation">
    ```shell theme={null}
    python3 -c "from ditto import Ditto; print(Ditto.version())"
    ```

    This imports the SDK, loads the native `libdittoffi` library, and prints the
    SDK version.
  </Step>
</Steps>

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

```python theme={null}
from ditto import Ditto, DittoConfig, DittoConfigConnect
```

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

```shell theme={null}
export DITTO_DATABASE_ID=""
export DITTO_DEVELOPMENT_TOKEN=""
export DITTO_SERVER_URL=""
```

```python Python theme={null}
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](/sdk/latest/api-reference/python).

## 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:

```shell theme={null}
export DITTOFFI_LIB_PATH="/path/to/libdittoffi"
```

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

1. `DITTOFFI_LIB_PATH`, if set.
2. The native library bundled with the installed `dittolive-ditto` package.
3. Directories in `DITTOFFI_SEARCH_PATH`.
4. A compatible build in a Ditto source checkout.
5. 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:

```shell theme={null}
export DITTOFFI_REQUIRE_BUNDLED=1
```


## Related topics

- [Go - Public Preview](/sdk/latest/install-guides/go.md)
- [Go Release Notes](/sdk/latest/release-notes/go.md)
- [Python Compatibility](/sdk/latest/compatibility/python.md)