supabase-py

supabase-py is the official Python SDK for Supabase, the open-source Firebase alternative built on Postgres. Rather than hand-rolling a database driver, an auth flow, and a storage client separately, create_client() returns a single Client object that composes five purpose-built sibling libraries — postgrest-py, supabase_auth, storage3, supabase_functions, and realtime-py — behind one ergonomic API that mirrors the JS supabase-js client Python developers may already know from the docs.

Both a synchronous Client and an AsyncClient are available from the same package, generated from a single source via unasync so the two code paths never drift apart. It’s built for Flask, Django, and FastAPI backends that need to query Postgres with row-level-security-aware calls, authenticate and manage users, upload/download files, invoke edge functions, or subscribe to realtime database changes — all through one dependency instead of stitching together separate clients for each concern.

What You Get

• A single create_client(url, key) entrypoint exposing .table(), .auth, .storage, .functions, and .realtime on one object
• Both sync (Client) and async (AsyncClient) variants generated from the same source so behavior stays identical across the two
• A typed Postgrest query builder (.table(...).select/insert/update/upsert/delete()) for Postgres access with row-level security respected
• Built-in auth client (sign up, sign in, session management, OAuth) re-exported from supabase_auth
• Storage client for uploading, downloading, listing, moving, and removing files in Supabase Storage buckets
• Edge Functions invocation with typed FunctionsHttpError/FunctionsRelayError exceptions for error handling
• Realtime channel subscriptions for listening to Postgres changes over WebSockets

Common Use Cases

• Backing a Flask, Django, or FastAPI API with Postgres queries and row-level-security-aware auth in one client
• Building data pipelines or Jupyter notebooks that read/write Supabase Postgres tables from Python
• Handling user sign-up/sign-in and session/token management server-side without a separate auth SDK
• Uploading and serving user files (images, documents) through Supabase Storage from a Python backend
• Streaming live database changes into a Python service via realtime channel subscriptions

Under The Hood

Architecture supabase-py is a uv workspace of six independently-versioned sub-packages (postgrest, storage3, supabase_auth, supabase_functions, realtime, and the top-level supabase package) that release-please pins to matching exact versions; the supabase package itself is a thin composition layer whose Client/AsyncClient classes (src/supabase/src/supabase/_sync/client.py and _async/client.py) lazily construct sub-clients for auth, postgrest, storage, and functions as properties and wire auth.on_auth_state_change callbacks into a shared header/session store, so a token refresh in the auth client automatically updates headers used by the Postgrest and Storage clients. Sync and async implementations are generated from one source via unasync, keeping the two APIs from drifting.

Tech Stack Built for Python 3.9 through 3.14, using httpx for HTTP transport and yarl for URL composition, with the five sibling Supabase packages (postgrest-py, supabase_auth, storage3, supabase_functions, realtime-py) as first-class dependencies pinned to exact release-please-managed versions. The workspace is managed with uv (uv.lock, uv2nix flake for reproducible Nix dev shells), linted with ruff (isort, pyupgrade, flake8-bugbear rule sets enabled), type-checked with mypy, and tested with pytest plus pytest-asyncio and pytest-cov, with coverage reported to Coveralls.

Code Quality Tests run against real, containerized Supabase services (Docker + the Supabase CLI spin up Postgres, Auth, Storage, and Realtime) rather than relying solely on mocks, with separate _sync/_async test trees mirroring the source split and environment-driven config (SUPABASE_TEST_URL/SUPABASE_TEST_KEY). The package ships a py.typed marker and is checked with mypy, and errors are surfaced through explicit typed exception classes (SupabaseException, and re-exported AuthApiError, StorageException, FunctionsHttpError, PostgrestAPIError) rather than being swallowed. CI runs the full matrix across six Python versions on every push and pull request.

API Design The API’s main strength is that it collapses five otherwise-independent SDKs behind one create_client() call and one Client object, closely mirroring the JS supabase-js client’s shape — so a developer who has seen the Supabase docs for any language can transfer that mental model directly to Python. Sync and async variants share an identical surface (create_client vs create_async_client), which removes the usual burden of learning two subtly different APIs for the same library.