Install & Compatibility
Where this runs
tested against v2.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✓ 8.7s
51MB installed
● package 51MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Surreal
✓ from surrealdb import Surreal
✗ from surrealdb import SurrealDB
In v2.x the class is named 'Surreal', not 'SurrealDB' as in older versions.
AsyncSurreal
✓ from surrealdb import AsyncSurreal
Async client class, available since v2.0.
Connect to SurrealDB, authenticate, use namespace/database, create and select records.
import os
from surrealdb import Surreal
url = os.environ.get('SURREAL_URL', 'ws://localhost:8000/rpc')
nspace = os.environ.get('SURREAL_NS', 'test')
dbname = os.environ.get('SURREAL_DB', 'test')
async def main():
async with Surreal(url) as db:
await db.signin({'user': 'root', 'pass': 'root'})
await db.use(nspace, dbname)
# Create a record
created = await db.create('person', {'name': 'John', 'age': 30})
print(created)
# Select all records
records = await db.select('person')
print(records)
import asyncio
asyncio.run(main())
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'surrealdb'
Library not installed or installed in wrong environment.
fixRun 'pip install surrealdb' in the correct Python environment.
AttributeError: module 'surrealdb' has no attribute 'SurrealDB'
Using old import path 'from surrealdb import SurrealDB' with v2.x.
fixUse 'from surrealdb import Surreal' instead.
TypeError: object Surreal can't be used in 'await' expression
Trying to use sync methods or forgetting 'async' on function definition.
fixEnsure all Surreal methods are called with 'await' inside an async function.
ConnectionRefusedError: [Errno 111] Connection refused
SurrealDB server not running or wrong URL/port.
fixVerify server is running and URL is correct (e.g., ws://localhost:8000/rpc).
Upgrade
Version history
2.0.0latest on PyPI · released Apr 23, 2026
Audit
Dependencies
websocketsrequiredRequired for WebSocket connection to SurrealDB.