Python SDK

Complete reference for the Supabase Python client library

Installation

Install the Supabase Python client library:

pip install supabase

Initializing

Create a Supabase client to interact with your database.

from supabase import create_client, Client
import os

url: str = os.environ.get("SUPABASE_URL")
key: str = os.environ.get("SUPABASE_KEY")
supabase: Client = create_client(url, key)

supabase_url · str · required

The unique Supabase URL for your project.

supabase_key · str · required

The Supabase anon key or service role key for your project.

options · ClientOptions

Optional configuration parameters.

Show options properties

schema · str · default: "public"

The database schema to use.

headers · dict

Custom headers to send with every request.

auto_refresh_token · bool · default: "True"

Automatically refresh the token before expiring.

persist_session · bool · default: "True"

Whether to persist the user session.

Database Operations

Select Data

Query data from your tables.

response = supabase.table('countries').select('*').execute()

data · list

The returned rows from the query.

count · int | None

The total count of rows (if count option is specified).

Select with Filters

response = supabase.table('countries') \
    .select('name, capital') \
    .eq('id', 1) \
    .single() \
    .execute()

Select with Joins

response = supabase.table('countries') \
    .select('name, cities(name, population)') \
    .execute()

Common Filters

# Equal to
response = supabase.table('countries').select('*').eq('name', 'Albania').execute()

# Not equal to
response = supabase.table('countries').select('*').neq('name', 'Albania').execute()

# Greater than
response = supabase.table('countries').select('*').gt('population', 1000000).execute()

# Less than
response = supabase.table('countries').select('*').lt('population', 1000000).execute()

# Like (pattern matching)
response = supabase.table('countries').select('*').like('name', '%Alba%').execute()

# In list
response = supabase.table('countries').select('*').in_('name', ['Albania', 'Algeria']).execute()

# Is null
response = supabase.table('countries').select('*').is_('capital', 'null').execute()

Insert Data

Insert rows into your tables.

data = supabase.table('countries').insert({
    'name': 'Denmark',
    'code': 'DK'
}).execute()

values · dict | list[dict] · required

The values to insert. Can be a single dictionary or a list of dictionaries.

data · list

The inserted rows.

Insert Multiple Rows

data = supabase.table('countries').insert([
    {'name': 'Denmark', 'code': 'DK'},
    {'name': 'Norway', 'code': 'NO'}
]).execute()

Update Data

Update existing rows in your tables.

data = supabase.table('countries') \
    .update({'name': 'Australia'}) \
    .eq('id', 1) \
    .execute()

values · dict · required

The values to update.

Upsert Data

Insert or update rows based on unique constraints.

data = supabase.table('countries') \
    .upsert({'id': 1, 'name': 'Australia'}) \
    .execute()

on_conflict · str

Specify which columns should be used for the conflict resolution.

Delete Data

Delete rows from your tables.

data = supabase.table('countries') \
    .delete() \
    .eq('id', 1) \
    .execute()

Authentication

Sign Up

Create a new user account.

response = supabase.auth.sign_up({
    'email': '[e-mail]',
    'password': 'example-password'
})

email · str · required

The user’s email address.

password · str · required

The user’s password.

options · dict

Optional parameters.

Show options properties

data · dict

Additional user metadata.

email_redirect_to · str

A URL to redirect to after signup.

captcha_token · str

Captcha token for verification.

user · User | None

The user object.

session · Session | None

The session object.

Sign In

Sign in an existing user.

response = supabase.auth.sign_in_with_password({
    'email': '[e-mail]',
    'password': 'example-password'
})

Sign Out

Sign out the current user.

supabase.auth.sign_out()

Get Session

Get the current session.

session = supabase.auth.get_session()

session · Session | None

The current session object or None if no active session.

Get User

Get the current user.

user = supabase.auth.get_user()

user · User | None

The current user object or None if not authenticated.

Storage

Upload File

Upload a file to a storage bucket.

with open('avatar.png', 'rb') as f:
    response = supabase.storage.from_('avatars').upload(
        path='public/avatar1.png',
        file=f,
        file_options={'content-type': 'image/png'}
    )

path · str · required

The file path including the file name.

file · bytes | BinaryIO · required

The file data to upload.

file_options · dict

Upload options.

Show file_options properties

cache-control · str

Cache control header value.

content-type · str

MIME type of the file.

upsert · bool · default: "False"

When True, overwrites existing file with the same path.

Download File

Download a file from storage.

response = supabase.storage.from_('avatars').download('public/avatar1.png')

path · str · required

The file path to download.

data · bytes

The file data as bytes.

List Files

List all files in a bucket.

files = supabase.storage.from_('avatars').list('public', {
    'limit': 100,
    'offset': 0,
    'sortBy': {'column': 'name', 'order': 'asc'}
})

Delete Files

Delete files from storage.

response = supabase.storage.from_('avatars').remove([
    'public/avatar1.png',
    'public/avatar2.png'
])

Get Public URL

Get the public URL for a file.

url = supabase.storage.from_('avatars').get_public_url('public/avatar1.png')
print(url)

Realtime

Subscribe to Changes

Listen to database changes in realtime.

def on_change(payload):
    print('Change received!', payload)

supabase.table('countries') \
    .on('*', on_change) \
    .subscribe()

event · str · required

The database event to listen for: INSERT, UPDATE, DELETE, or * for all.

callback · Callable · required

Function to call when an event occurs.

Unsubscribe

Stop listening to changes.

supabase.table('countries').unsubscribe()

Edge Functions

Invoke Function

Invoke a Supabase Edge Function.

response = supabase.functions.invoke(
    'hello-world',
    invoke_options={'body': {'name': 'Functions'}}
)

function_name · str · required

The name of the Edge Function to invoke.

invoke_options · dict

Function invocation options.

Show invoke_options properties

body · dict

The request body to send to the function.

headers · dict

Custom headers to send with the request.

method · str · default: "POST"

HTTP method to use.

data · any

The response data from the function.

Type Hints

The Python client supports type hints:

from supabase import Client, create_client
from typing import List, Dict

supabase: Client = create_client(url, key)

response = supabase.table('countries').select('*').execute()
data: List[Dict] = response.data

Error Handling

Handle errors using try-except blocks:

try:
    response = supabase.table('countries').select('*').execute()
    data = response.data
except Exception as e:
    print(f'Error: {e}')

Async Support

Use the async client for asynchronous operations:

import asyncio
from supabase import create_async_client

async def main():
    supabase = await create_async_client(url, key)
    response = await supabase.table('countries').select('*').execute()
    print(response.data)

asyncio.run(main())

Additional Resources

GitHub Repository

View the source code and contribute

PyPI Package

View package details and versions