> ## 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 Console App Quickstart

> Get started quickly with Ditto using the Ditto Quickstart Applications

export const QuickstartSyncDataOfflineBody = () => <div>
        <ol>
            <li>Launch the application on multiple devices or simulators</li>
            <li>Disconnect from your current WiFi network while keeping WiFi enabled on the device to allow for LAN connections</li>
            <li>Add, edit, and delete tasks and experience offline collaboration!</li>
        </ol>
    </div>;

export const QuickstartCloneTheRepoBody = () => <div>
        <ol>
            <li>Open the terminal</li>
            <li>
                Clone the repository from GitHub.
                <pre>
                    <code>
                        git clone https://github.com/getditto/quickstart
                    </code>
                </pre>
            </li>
            <li>
                Navigate to the project directory:
                <pre>
                    <code>
                        cd quickstart
                    </code>
                </pre>
            </li>
        </ol>
    </div>;

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

## Prerequisites

Ditto's Python Quickstart supports **Linux** and **macOS** only. Before getting started, ensure you have the following:

* [Git](https://git-scm.com/) installed on your machine
* [Python](https://www.python.org/) 3.10 or later installed on your machine (3.10–3.13 are supported)
* A Ditto [Portal](https://portal.ditto.live) account with a configured Ditto Database

We recommend [uv](https://docs.astral.sh/uv/), which installs the Python
interpreter and dependencies for you. The quickstart also runs with `pip` and a
virtual environment.

## Get Started

### 1. Clone the Repository

<QuickstartCloneTheRepoBody />

The project directory contains quickstart applications for all SDKs supported by Ditto including Python.

### 2. Configure Ditto

#### Get your connection details

In the Ditto Portal, select your database and select the **Connect via SDK** tab. Then copy the following values:

* Database ID
* Development Token
* URL

URL is the Ditto Server URL the SDK uses to connect to your Ditto database.

#### Add Ditto Credentials

1. Copy the `.env.sample` file in the `quickstart` directory to `.env`.
   ```shell theme={null}
   cd quickstart
   cp .env.sample .env
   ```
2. Update the `.env` file with the Database ID, Development Token, and URL
   from the Ditto Portal.
   ```shell theme={null}
   DITTO_DATABASE_ID="REPLACE_ME_WITH_YOUR_DATABASE_ID"
   DITTO_DEVELOPMENT_TOKEN="REPLACE_ME_WITH_YOUR_DEVELOPMENT_TOKEN"
   DITTO_SERVER_URL="REPLACE_ME_WITH_YOUR_URL"
   ```

### 3. Run the Application

Run one of the following commands. The `uv` and `pip` commands start from the
`python-tui` directory; run the `just` command from the `quickstart` directory.

<CodeGroup>
  ```shell uv theme={null}
  cd python-tui
  uv run --with dittolive-ditto main.py
  ```

  ```shell pip theme={null}
  cd python-tui
  python3 -m venv .venv
  source .venv/bin/activate
  pip install --pre dittolive-ditto
  python main.py
  ```

  ```shell just theme={null}
  just python-tui
  ```
</CodeGroup>

Once running, manage the task list with these commands:

| Command            | Description                     |
| ------------------ | ------------------------------- |
| `add <title>`      | Create a task                   |
| `toggle <n>`       | Toggle a task's completed state |
| `edit <n> <title>` | Rename a task                   |
| `del <n>`          | Delete a task                   |
| `list`             | Refresh the list                |
| `quit`             | Exit                            |

Press Enter (or type `list`) to refresh and pick up changes made by other peers.

### 4. Sync-Data Offline

<QuickstartSyncDataOfflineBody />

## Optional: Run a Local Smoke Test

To check that the SDK is installed and working without using any credentials or
network access, run the quickstart's self-test. The `uv` and `pip` commands
start from the `python-tui` directory; run the `just` command from the
`quickstart` directory.

<CodeGroup>
  ```shell uv theme={null}
  cd python-tui
  uv run --with dittolive-ditto main.py --smoke
  ```

  ```shell pip theme={null}
  cd python-tui
  source .venv/bin/activate
  python main.py --smoke
  ```

  ```shell just theme={null}
  just python-tui-smoke
  ```
</CodeGroup>

This checks local task changes without connecting to Ditto Server.

## Next Steps

All the Ditto Quickstart apps work together! Try running a quickstart app in other languages and see them all collaborate.

## Additional Resources

* [Python Install Guide](/sdk/latest/install-guides/python)
* [Python Compatibility](/sdk/latest/compatibility/python)
* [API Reference](/sdk/latest/api-reference/python)


## Related topics

- [C++ Console App Quickstart](/sdk/latest/quickstarts/cpp-console.md)
- [.NET (C#) Console App Quickstart](/sdk/latest/quickstarts/dotnet-console.md)
- [Rust Console App Quickstart](/sdk/latest/quickstarts/rust-console.md)