Installation

This page shows how to install the Python SDK, choose its optional extras, and import it into a project. The SDK needs Python 3.10 or later.

Install the SDK

Install the SurrealDB SDK from PyPI:

pip install surrealdb

With uv:

uv add surrealdb

To check the installed version:

pip show surrealdb

The default install connects to a remote SurrealDB instance over WebSocket or HTTP. It depends on websockets 15.0 or later, aiohttp 3.14.0 or later, requests and pydantic-core.

Install optional extras

Three features ship as extras, so that a project installs only what it uses:

With uv, use the same names: uv add "surrealdb[embedded]". To install more than one extra, separate them with commas: pip install "surrealdb[embedded,pydantic]".

Without the embedded extra, an embedded URL raises UnsupportedEngineError with the command to install it. The embedded engine has prebuilt wheels for macOS on Intel and Apple silicon, Linux on x86-64 and ARM64 (glibc and musl), and Windows on x86-64. On other platforms, pip builds it from source, which needs Rust 1.95 or later.

Import the SDK into your project

The SDK has a factory function for each style of code. For blocking code, such as scripts and command-line tools:

from surrealdb import Surreal

For applications that use asyncio:

from surrealdb import AsyncSurreal

Both take a connection URL and return the connection class for its scheme. The value types, such as RecordID and Table, and the error classes are exported from surrealdb too:

from surrealdb import AsyncSurreal, RecordID, SurrealError, Table

Next steps

• •

  Getting started for a complete working example

• •

  Connecting to SurrealDB for connection options and protocols

• •

  Authentication for signing in and managing credentials

• •

  Migrating to Python SDK 3.x if you are upgrading from version 2