supabase-py

Python monorepo for all Supabase libraries.

• supabase
• realtime-py
• supabase_functions
• storage3
• postgrest
• supabase_auth

Relevant links:

• Documentation: supabase.com/docs
• Usage:
  • GitHub OAuth in your Python Flask app
  • Python data loading with Supabase

Support Policy

Python

We support every Python version that has not yet reached end of life, as listed in the Python version status page. The currently supported versions are the ones tested in CI.

Once a Python version reaches end of life, support for it may be dropped in a minor release, and this won't be considered a breaking change. For instance, Python 3.9 reached end of life in October 2025, so it can be removed in a minor update.

Platforms

The libraries are pure Python and are tested on Linux. They are expected to work on any platform supported by CPython, such as macOS and Windows.

Important

Only CPython is officially supported. Alternative Python implementations, such as PyPy, may work but aren't tested, and may stop working in future versions of the library.

Supabase Service Compatibility

supabase-py only guarantees compatibility with the latest release of each Supabase service, unless a minimum supported version is explicitly listed below.

Older service releases are supported on a best-effort basis, but compatibility is not guaranteed.

If you self-host Supabase, we recommend upgrading your services to their latest releases when upgrading the SDK.

Service	SDK package	Server releases	Lowest supported version
Auth	supabase_auth	supabase/auth	Latest release
Storage	storage3	supabase/storage	Latest release
Functions	supabase_functions	supabase/edge-runtime	Latest release
PostgREST	postgrest	PostgREST/postgrest	Latest release
Realtime	realtime	supabase/realtime	Latest release

Local Development

Clone the Repository

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

Dependencies

This repository relies on the following dependencies for development:

• uv for python project management.
• make for running project commands.
• docker for both postgrest and auth test containers.
• supabase-cli for both storage and realtime test containers.

All of these dependencies are included in the nix shell environment, through flake.nix. If you've got nix installed, you may prefer to use it through nix develop.

Use a Virtual Environment

We recommend using a virtual environment, preferably through uv, given it is currently the only tool that understands the workspace setup (you can read more about it in the uv docs).

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

If you're using nix, the generated python executable should have the correct dependencies installed for the whole workspace, given it is derived from the root's pyproject.toml using uv2nix.

Running tests and other commands

We use make to store and run the relevant commands. The structure is set up such that each sub package can individually set its command in its own Makefile, and the job of the main Makefile is just coordinate calling each of them.

For instance, in order to run all tests of all packages, you should use the following root command

make ci

Which internally dispatches make -C src/{package} tests calls to each package in the monorepo.

You should also consider using

make ci -jN # where N is the number of max concurrent jobs, or just -j for infinite jobs

To run each of the packages' tests in parallel. This should be generally faster than running in 1 job, but has the downside of messing up the CLI output, so parsing error messages might not be easy.

Other relevant commands include

make install-hooks # install all commit hooks into the local .git folder
make stop-infra    # stops all running containers from all packages
make clean         # delete all intermediary files created by testing

All the subpackages command are available from the main root by prefixing the command with {package_name}.. Examples:

make realtime.tests # run only realtime tests
make storage.clean  # delete temporary files only in the storage package