supabase-py: the Python client for Postgres, auth, storage and realtime

What supabase-py actually is, and who it is for

This repository is not a single library. The root pyproject.toml declares a uv workspace with six members: src/realtime, src/functions, src/supabase, src/storage, src/postgrest and src/auth. Each one is published separately, and the umbrella package named supabase depends on the others through workspace sources. If you install supabase from PyPI you get the client that re-exports the rest, so a single import can reach Postgres queries, authentication, file storage, edge functions and realtime streams.

The intended audience is a Python backend developer who has a Supabase project and does not want to hand-roll HTTP calls to PostgREST or GoTrue. The README points at Flask, Django and FastAPI in the project description, and the linked usage posts cover GitHub OAuth in a Flask app and data loading from Python. Nothing in the repository restricts it to a web framework; the client is plain Python, and the async support that the search results ask about comes from the underlying HTTP layer rather than a framework adapter.

How the six packages fit together

The architecture is a thin client over Supabase's HTTP and websocket services. postgrest builds query objects that serialize into PostgREST request parameters, so a table read becomes a URL with filter and select clauses rather than a SQL string you assemble. supabase_auth handles sign-up, sign-in and session state against the auth service. storage3 covers buckets and objects. realtime maintains a websocket connection for change events. supabase_functions invokes edge functions.

The umbrella package is the coordination point. Its job, based on the workspace layout, is to hold one configured client and expose each subsystem as an attribute, which is why the root README lists the sub-package READMEs instead of repeating their APIs. That split matters when you debug: an error from a filter chain is a postgrest concern, while an expired session is an auth concern, and the root documentation will not explain either in depth. The per-package READMEs under src/ are where the detail lives.

Installing supabase-py and running a first query

The published distribution is named supabase on PyPI, which is what the badge in the README points to. The README does not print a pip install line at the root, so the install step is the one you would expect for a package published under that name, and the repository's own setup instructions are for contributors. The README gives this sequence for a development checkout.

git clone https://github.com/supabase/supabase-py.git
cd supabase-py

Dependencies for development are uv for project management, make for running project commands, docker for the postgrest and auth test containers, and supabase-cli for the storage and realtime test containers. The README says all of these are included in the nix shell environment through flake.nix, so nix develop is an alternative to installing them yourself.

The README then recommends a virtual environment, preferably through uv, because it says uv is currently the only tool that understands the workspace setup.

uv venv supabase-py
source supabase-py/bin/activate
uv sync

Once the environment is synced, the suite runs through make. The root target dispatches a make -C src/{package} tests call to each package in the monorepo.

make ci

The README notes that make ci -jN, where N is the number of max concurrent jobs, runs the packages' tests in parallel and is generally faster, with the downside that the CLI output is interleaved and parsing error messages becomes harder. Other root commands the README lists include make install-hooks, make stop-infra and make clean, and any sub-package command is reachable from the root by prefixing it with the package name, as in make realtime.tests or make storage.clean.

For actual use of the library rather than the repository, the README points to the Python documentation at supabase.com/docs/reference/python and to the per-package READMEs under src/, which is where the client construction and query examples live.

Where supabase-py stops being the right tool

The client speaks to Supabase's own services. It is not a general Postgres driver, so anything that needs a raw connection, a server-side cursor, a long transaction, or a query shape PostgREST cannot express is outside what the library does. If your work is mostly analytical SQL, a direct driver plus your own connection pool is the more honest choice, and supabase-py will only add an HTTP hop.

The root README is also thin on the umbrella package itself. It lists the sub-package READMEs and links to Supabase documentation, but it does not walk through authentication flows, storage uploads or realtime subscription setup. A reader who only opens the root file will not learn how to keep a session alive or how to resubscribe after a dropped websocket. That is a documentation boundary, not a defect in the code, but it changes how much time you spend in src/auth and src/realtime before you can ship.

Version pinning deserves attention too. The repository targets py39 in its ruff configuration, which tells you the lint target, not the support matrix of every published wheel. Check the package metadata for the version you pin rather than inferring support from the repository tooling.

supabase-py against a plain Postgres driver

The real alternative for most teams is psycopg or SQLAlchemy talking straight to Postgres, with a separate auth library. The difference is where the work sits. A plain driver gives you SQL, transactions and connection control, and you own session management, storage and realtime yourself. supabase-py gives you a managed surface: PostgREST turns your filter chain into an HTTP request, GoTrue issues and refreshes tokens, and the storage and realtime packages cover the rest.

That trade is visible in the query model. With SQLAlchemy you write the statement and read the generated SQL. With supabase-py you build a chain of method calls and the SQL is generated by PostgREST on the server, which is convenient until you need a join or a window function that the API does not expose. Teams that expect to grow into complex reporting usually keep a direct Postgres connection alongside the client for exactly this reason, rather than trying to force every query through the REST layer.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-09-09, so the project is being worked on. Releases arrive through release-please, with a manifest and config file at the root, and the recent tags run v2.30.0, v2.30.1 and v2.31.0 between May and June 2026. The monorepo publishes per-package versions, so an upgrade is not a single decision: the umbrella client, postgrest, supabase_auth, storage3, realtime and supabase_functions can move independently, and a workspace source in development does not tell you how the published wheels pin each other.

Upgrade cost therefore depends on which subsystem you touch. A postgrest change can alter how a filter serializes without any change to the auth surface. The practical check before bumping is the changelog and the per-package README for the package whose behaviour you rely on. The licence is MIT, which permits commercial use and modification; the repository also carries MAINTAINERS.md and CONTRIBUTING.md, and the README describes a commit hook installed through make install-hooks that runs commitizen against your commit message. This is a description of the licence terms, not legal advice, and you should read the LICENSE file yourself.

Editorial conclusion

Adopt supabase-py when your backend is Python and your data already lives in a Supabase project, because the umbrella client wraps PostgREST, GoTrue, Storage and Realtime behind one object. Skip it if you need raw SQL control, a synchronous-only stack with no async path, or a database that is not Postgres. Before committing, verify the Python version supported by the package you pin, check whether the auth helpers you need are documented in the per-package READMEs rather than the root one, and confirm your deployment can reach the project URL and keys you plan to use.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. supabase/supabase-py on GitHub