# `supabase-py`
Python client for [Supabase](https://supabase.com)
- Documentation: [supabase.com/docs](https://supabase.com/docs/reference/python/introduction)
- Usage:
- [GitHub OAuth in your Python Flask app](https://supabase.com/blog/oauth2-login-python-flask-apps)
- [Python data loading with Supabase](https://supabase.com/blog/loading-data-supabase-python)
## Set up a Local Development Environment
### Clone the Repository
```bash
git clone https://github.com/supabase/supabase-py.git
cd supabase-py
```
### Create and Activate a Virtual Environment
We recommend activating your virtual environment. For example, we like `uv` and `conda`! Click [here](https://docs.python.org/3/library/venv.html) for more about Python virtual environments and working with [conda](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#activating-an-environment) and [uv](https://docs.astral.sh/uv/getting-started/features/).
Using uv:
```
uv venv supabase-py
source supabase-py/bin/activate
```
Using venv (Python 3 built-in):
```bash
python3 -m venv env
source env/bin/activate # On Windows, use .\env\Scripts\activate
```
Using conda:
```bash
conda create --name supabase-py
conda activate supabase-py
```
### PyPI installation
Install the package (for Python >= 3.9):
```bash
# with pip
pip install supabase
# with conda
conda install -c conda-forge supabase
```
### Local installation
You can also install locally after cloning this repo. Install Development mode with `pip install -e`, which makes it editable, so when you edit the source code the changes will be reflected in your python module.
## Usage
Set your Supabase environment variables in a dotenv file, or using the shell:
```bash
export SUPABASE_URL="my-url-to-my-awesome-supabase-instance"
export SUPABASE_KEY="my-supa-dupa-secret-supabase-api-key"
```
Init client:
```python
import os
from supabase import create_client, Client
url: str = os.environ.get("SUPABASE_URL")
key: str = os.environ.get("SUPABASE_KEY")
supabase: Client = create_client(url, key)
```
Use the supabase client to interface with your database.
### Sign-up
```python
user = supabase.auth.sign_up({ "email": users_email, "password": users_password })
```
### Sign-in
```python
user = supabase.auth.sign_in_with_password({ "email": users_email, "password": users_password })
```
### Insert Data
```python
data = supabase.table("countries").insert({"name":"Germany"}).execute()
# Assert we pulled real data.
assert len(data.data) > 0
```
### Select Data
```python
data = supabase.table("countries").select("*").eq("country", "IL").execute()
# Assert we pulled real data.
assert len(data.data) > 0
```
### Update Data
```python
data = supabase.table("countries").update({"country": "Indonesia", "capital_city": "Jakarta"}).eq("id", 1).execute()
```
### Update data with duplicate keys
```python
country = {
"country": "United Kingdom",
"capital_city": "London" # This was missing when it was added
}
data = supabase.table("countries").upsert(country).execute()
assert len(data.data) > 0
```
### Delete Data
```python
data = supabase.table("countries").delete().eq("id", 1).execute()
```
### Call Edge Functions
```python
def test_func():
try:
resp = supabase.functions.invoke("hello-world", invoke_options={'body':{}})
return resp
except (FunctionsRelayError, FunctionsHttpError) as exception:
err = exception.to_dict()
print(err.get("message"))
```
### Download a file from Storage
```python
bucket_name: str = "photos"
data = supabase.storage.from_(bucket_name).download("photo1.png")
```
### Upload a file
```python
bucket_name: str = "photos"
new_file = getUserFile()
data = supabase.storage.from_(bucket_name).upload("/user1/profile.png", new_file)
```
### Remove a file
```python
bucket_name: str = "photos"
data = supabase.storage.from_(bucket_name).remove(["old_photo.png", "image5.jpg"])
```
### List all files
```python
bucket_name: str = "charts"
data = supabase.storage.from_(bucket_name).list()
```
### Move and rename files
```python
bucket_name: str = "charts"
old_file_path: str = "generic/graph1.png"
new_file_path: str = "important/revenue.png"
data = supabase.storage.from_(bucket_name).move(old_file_path, new_file_path)
```
## Roadmap
- [x] Wrap [Postgrest-py](https://github.com/supabase/postgrest-py/)
- [x] Add remaining filters
- [x] Add support for EXPLAIN
- [ ] Add proper error handling
- [x] Use `sanitize_param()` to sanitize inputs.
- [x] Fix client-side timeouts for long running queries.
- [x] Enable HTTP2 by default.
- [x] Enable follow redirects by default.
- [x] Enable keep-alive by default.
- [x] Enable running with unverified SSL via `verify=False`.
- [x] Add Stalebot.
- [x] Update CI (linters, etc).
- [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).
- [ ] Wrap [Realtime-py](https://github.com/supabase/realtime-py)
- [ ] Integrate with Supabase-py
- [ ] Support WALRUS
- [ ] Support broadcast (to check if already supported)
- [x] Add `close()` method to close a socket.
- [x] Add Stalebot.
- [x] Update CI (linters, etc).
- [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).
- [x] Wrap [auth-py](https://github.com/supabase/auth-py)
- [x] Remove references to GoTrue-js v1 and do a proper release
- [ ] Test and document common flows (e.g. sign in with OAuth, sign in with OTP)
- [ ] Add MFA methods
- [x] Add SSO methods
- [x] Add Proof Key for Code Exchange (PKCE) methods. Unlike the JS library, we do not currently plan to support Magic Link (PKCE). Please use the [token hash](https://supabase.com/docs/guides/auth/server-side/email-based-auth-with-pkce-flow-for-ssr#create-api-endpoint-for-handling-tokenhash) in tandem with `verifyOTP` instead.
- [x] Add `is_anonymous` boolean property.
- [x] Add `sign_in_with_id_token()` method.
- [x] Add `sign_in_with_sso()` method.
- [x] Enable HTTP2 by default.
- [x] Enable follow redirects by default.
- [x] Enable keep-alive by default.
- [x] Enable running with unverified SSL via `verify=False`.
- [x] Add Stalebot.
- [x] Update CI (linters, etc).
- [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).
- [x] Wrap [storage-py](https://github.com/supabase/storage-py)
- [ ] Support resumable uploads
- [x] Setup testing environment
- [x] Fix client-side timeouts for long running operations.
- [x] Enable HTTP2 by default.
- [x] Enable follow redirects by default.
- [x] Enable keep-alive by default.
- [x] Enable running with unverified SSL via `verify=False`.
- [x] Add Stalebot.
- [x] Update CI (linters, etc).
- [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).
- [x] Document how to properly upload different file types (e.g. jpeg/png and download it)
- [x] Wrap [functions-py](https://github.com/supabase/functions-py)
- [x] Fix client-side timeouts for long running functions.
- [x] Enable HTTP2 by default.
- [x] Enable follow redirects by default.
- [x] Enable keep-alive by default.
- [x] Enable running with unverified SSL via `verify=False`.
- [x] Add Regions support.
- [x] Add Stalebot.
- [x] Update CI (linters, etc).
- [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).
### Overall Tasks
- [x] Add async support across the entire library
- [ ] Add FastAPI helper library (external to supabase-py)
- [ ] Add `django-supabase-postgrest` (external to supabase-py)
## Contributing
Contributing to the Python libraries are a great way to get involved with the Supabase community. Reach out to us on [Discord](https://discord.supabase.com) or on our [Github Discussions](https://github.com/orgs/supabase/discussions) page if you want to get involved.
## Important: Proper Client Shutdown
To ensure the Supabase client terminates correctly and to prevent resource leaks, you **must** explicitly call:
```python
client.auth.sign_out()
```
### Running Tests
Currently, the test suites are in a state of flux. We are expanding our clients' tests to ensure things are working, and for now can connect to this test instance, which is populated with the following table:
<p align="center">
<img width="720" height="481" src="https://i.ibb.co/Bq7Kdty/db.png">
</p>
The above test database is a blank supabase instance that has populated the `countries` table with the built-in countries script that can be found in the supabase UI. You can launch the test scripts and point to the above test database by running
```bash
./test.sh
```
## Badges
[](https://opensource.org/licenses/MIT)
[](https://github.com/supabase/supabase-py/actions/workflows/ci.yml)
[](https://pypi.org/project/supabase)
[](https://pypi.org/project/supabase)
[](https://codecov.io/gh/supabase/supabase-py)
[](https://github.com/supabase/supabase-py/commits)
[](https://github.com/supabase/supabase-py/commits)
[](https://github.com/supabase/supabase-py/stargazers)
[](https://github.com/supabase/supabase-py/network/members)
[](https://github.com/supabase/supabase-py)
[](https://github.com/supabase/supabase-py/graphs/contributors)
Raw data
{
"_id": null,
"home_page": null,
"name": "supabase",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Joel Lee, Leon Fedden, Daniel Rein\u00f3n Garc\u00eda, Leynier Guti\u00e9rrez Gonz\u00e1lez, Anand, Andrew Smith",
"author_email": "Joel Lee <joel@joellee.org>, Leon Fedden <leonfedden@gmail.com>, Daniel Rein\u00f3n Garc\u00eda <danielreinon@outlook.com>, Leynier Guti\u00e9rrez Gonz\u00e1lez <leynier41@gmail.com>, Andrew Smith <a.smith@silentworks.co.uk>",
"download_url": "https://files.pythonhosted.org/packages/99/d2/3b135af55dd5788bd47875bb81f99c870054b990c030e51fd641a61b10b5/supabase-2.18.1.tar.gz",
"platform": null,
"description": "# `supabase-py`\n\nPython client for [Supabase](https://supabase.com)\n\n- Documentation: [supabase.com/docs](https://supabase.com/docs/reference/python/introduction)\n- Usage:\n - [GitHub OAuth in your Python Flask app](https://supabase.com/blog/oauth2-login-python-flask-apps)\n - [Python data loading with Supabase](https://supabase.com/blog/loading-data-supabase-python)\n\n## Set up a Local Development Environment\n\n### Clone the Repository\n\n```bash\ngit clone https://github.com/supabase/supabase-py.git\ncd supabase-py\n```\n\n### Create and Activate a Virtual Environment\n\nWe recommend activating your virtual environment. For example, we like `uv` and `conda`! Click [here](https://docs.python.org/3/library/venv.html) for more about Python virtual environments and working with [conda](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#activating-an-environment) and [uv](https://docs.astral.sh/uv/getting-started/features/).\n\nUsing uv:\n```\nuv venv supabase-py\nsource supabase-py/bin/activate\n```\n\nUsing venv (Python 3 built-in):\n\n```bash\npython3 -m venv env\nsource env/bin/activate # On Windows, use .\\env\\Scripts\\activate\n```\n\nUsing conda:\n\n```bash\nconda create --name supabase-py\nconda activate supabase-py\n```\n\n### PyPI installation\n\nInstall the package (for Python >= 3.9):\n\n```bash\n# with pip\npip install supabase\n\n# with conda\nconda install -c conda-forge supabase\n```\n\n### Local installation\n\nYou can also install locally after cloning this repo. Install Development mode with `pip install -e`, which makes it editable, so when you edit the source code the changes will be reflected in your python module.\n\n## Usage\n\nSet your Supabase environment variables in a dotenv file, or using the shell:\n\n```bash\nexport SUPABASE_URL=\"my-url-to-my-awesome-supabase-instance\"\nexport SUPABASE_KEY=\"my-supa-dupa-secret-supabase-api-key\"\n```\n\nInit client:\n\n```python\nimport os\nfrom supabase import create_client, Client\n\nurl: str = os.environ.get(\"SUPABASE_URL\")\nkey: str = os.environ.get(\"SUPABASE_KEY\")\nsupabase: Client = create_client(url, key)\n```\n\nUse the supabase client to interface with your database.\n\n### Sign-up\n\n```python\nuser = supabase.auth.sign_up({ \"email\": users_email, \"password\": users_password })\n```\n\n### Sign-in\n\n```python\nuser = supabase.auth.sign_in_with_password({ \"email\": users_email, \"password\": users_password })\n```\n\n### Insert Data\n\n```python\ndata = supabase.table(\"countries\").insert({\"name\":\"Germany\"}).execute()\n\n# Assert we pulled real data.\nassert len(data.data) > 0\n```\n\n### Select Data\n\n```python\ndata = supabase.table(\"countries\").select(\"*\").eq(\"country\", \"IL\").execute()\n\n# Assert we pulled real data.\nassert len(data.data) > 0\n```\n\n### Update Data\n\n```python\ndata = supabase.table(\"countries\").update({\"country\": \"Indonesia\", \"capital_city\": \"Jakarta\"}).eq(\"id\", 1).execute()\n```\n\n### Update data with duplicate keys\n\n```python\ncountry = {\n \"country\": \"United Kingdom\",\n \"capital_city\": \"London\" # This was missing when it was added\n}\n\ndata = supabase.table(\"countries\").upsert(country).execute()\nassert len(data.data) > 0\n```\n\n### Delete Data\n\n```python\ndata = supabase.table(\"countries\").delete().eq(\"id\", 1).execute()\n```\n\n### Call Edge Functions\n\n```python\ndef test_func():\n try:\n resp = supabase.functions.invoke(\"hello-world\", invoke_options={'body':{}})\n return resp\n except (FunctionsRelayError, FunctionsHttpError) as exception:\n err = exception.to_dict()\n print(err.get(\"message\"))\n```\n\n### Download a file from Storage\n\n```python\nbucket_name: str = \"photos\"\n\ndata = supabase.storage.from_(bucket_name).download(\"photo1.png\")\n```\n\n### Upload a file\n\n```python\nbucket_name: str = \"photos\"\nnew_file = getUserFile()\n\ndata = supabase.storage.from_(bucket_name).upload(\"/user1/profile.png\", new_file)\n```\n\n### Remove a file\n\n```python\nbucket_name: str = \"photos\"\n\ndata = supabase.storage.from_(bucket_name).remove([\"old_photo.png\", \"image5.jpg\"])\n```\n\n### List all files\n\n```python\nbucket_name: str = \"charts\"\n\ndata = supabase.storage.from_(bucket_name).list()\n```\n\n### Move and rename files\n\n```python\nbucket_name: str = \"charts\"\nold_file_path: str = \"generic/graph1.png\"\nnew_file_path: str = \"important/revenue.png\"\n\ndata = supabase.storage.from_(bucket_name).move(old_file_path, new_file_path)\n```\n\n\n## Roadmap\n\n- [x] Wrap [Postgrest-py](https://github.com/supabase/postgrest-py/)\n - [x] Add remaining filters\n - [x] Add support for EXPLAIN\n - [ ] Add proper error handling\n - [x] Use `sanitize_param()` to sanitize inputs.\n - [x] Fix client-side timeouts for long running queries.\n - [x] Enable HTTP2 by default.\n - [x] Enable follow redirects by default.\n - [x] Enable keep-alive by default.\n - [x] Enable running with unverified SSL via `verify=False`.\n - [x] Add Stalebot.\n - [x] Update CI (linters, etc).\n - [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).\n\n- [ ] Wrap [Realtime-py](https://github.com/supabase/realtime-py)\n - [ ] Integrate with Supabase-py\n - [ ] Support WALRUS\n - [ ] Support broadcast (to check if already supported)\n - [x] Add `close()` method to close a socket.\n - [x] Add Stalebot.\n - [x] Update CI (linters, etc).\n - [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).\n\n- [x] Wrap [auth-py](https://github.com/supabase/auth-py)\n - [x] Remove references to GoTrue-js v1 and do a proper release\n - [ ] Test and document common flows (e.g. sign in with OAuth, sign in with OTP)\n - [ ] Add MFA methods\n - [x] Add SSO methods\n - [x] Add Proof Key for Code Exchange (PKCE) methods. Unlike the JS library, we do not currently plan to support Magic Link (PKCE). Please use the [token hash](https://supabase.com/docs/guides/auth/server-side/email-based-auth-with-pkce-flow-for-ssr#create-api-endpoint-for-handling-tokenhash) in tandem with `verifyOTP` instead.\n - [x] Add `is_anonymous` boolean property.\n - [x] Add `sign_in_with_id_token()` method.\n - [x] Add `sign_in_with_sso()` method.\n - [x] Enable HTTP2 by default.\n - [x] Enable follow redirects by default.\n - [x] Enable keep-alive by default.\n - [x] Enable running with unverified SSL via `verify=False`.\n - [x] Add Stalebot.\n - [x] Update CI (linters, etc).\n - [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).\n\n- [x] Wrap [storage-py](https://github.com/supabase/storage-py)\n - [ ] Support resumable uploads\n - [x] Setup testing environment\n - [x] Fix client-side timeouts for long running operations.\n - [x] Enable HTTP2 by default.\n - [x] Enable follow redirects by default.\n - [x] Enable keep-alive by default.\n - [x] Enable running with unverified SSL via `verify=False`.\n - [x] Add Stalebot.\n - [x] Update CI (linters, etc).\n - [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).\n - [x] Document how to properly upload different file types (e.g. jpeg/png and download it)\n\n- [x] Wrap [functions-py](https://github.com/supabase/functions-py)\n - [x] Fix client-side timeouts for long running functions.\n - [x] Enable HTTP2 by default.\n - [x] Enable follow redirects by default.\n - [x] Enable keep-alive by default.\n - [x] Enable running with unverified SSL via `verify=False`.\n - [x] Add Regions support.\n - [x] Add Stalebot.\n - [x] Update CI (linters, etc).\n - [x] Check cyclomatic complexity and fix if needed (mccabe, prospector).\n\n\n### Overall Tasks\n\n- [x] Add async support across the entire library\n- [ ] Add FastAPI helper library (external to supabase-py)\n- [ ] Add `django-supabase-postgrest` (external to supabase-py)\n\n## Contributing\n\nContributing to the Python libraries are a great way to get involved with the Supabase community. Reach out to us on [Discord](https://discord.supabase.com) or on our [Github Discussions](https://github.com/orgs/supabase/discussions) page if you want to get involved.\n\n## Important: Proper Client Shutdown\n\nTo ensure the Supabase client terminates correctly and to prevent resource leaks, you **must** explicitly call:\n\n```python\nclient.auth.sign_out()\n```\n\n### Running Tests\n\nCurrently, the test suites are in a state of flux. We are expanding our clients' tests to ensure things are working, and for now can connect to this test instance, which is populated with the following table:\n\n<p align=\"center\">\n <img width=\"720\" height=\"481\" src=\"https://i.ibb.co/Bq7Kdty/db.png\">\n</p>\n\nThe above test database is a blank supabase instance that has populated the `countries` table with the built-in countries script that can be found in the supabase UI. You can launch the test scripts and point to the above test database by running\n\n```bash\n./test.sh\n```\n\n## Badges\n\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/supabase/supabase-py/actions/workflows/ci.yml)\n[](https://pypi.org/project/supabase)\n[](https://pypi.org/project/supabase)\n[](https://codecov.io/gh/supabase/supabase-py)\n[](https://github.com/supabase/supabase-py/commits)\n[](https://github.com/supabase/supabase-py/commits)\n[](https://github.com/supabase/supabase-py/stargazers)\n[](https://github.com/supabase/supabase-py/network/members)\n[](https://github.com/supabase/supabase-py)\n[](https://github.com/supabase/supabase-py/graphs/contributors)\n",
"bugtrack_url": null,
"license": null,
"summary": "Supabase client for Python.",
"version": "2.18.1",
"project_urls": {
"documentation": "https://github.com/supabase/supabase-py",
"homepage": "https://github.com/supabase/supabase-py",
"repository": "https://github.com/supabase/supabase-py"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a8330e0062fea22cfe01d466dee83f56b3ed40c89bdcbca671bafeba3fe86b92",
"md5": "c2328b36a4862fb50db6bb049f8f02f7",
"sha256": "4fdd7b7247178a847f97ecd34f018dcb4775e487c8ff46b1208a01c933691fe9"
},
"downloads": -1,
"filename": "supabase-2.18.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2328b36a4862fb50db6bb049f8f02f7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 18683,
"upload_time": "2025-08-12T19:02:26",
"upload_time_iso_8601": "2025-08-12T19:02:26.680716Z",
"url": "https://files.pythonhosted.org/packages/a8/33/0e0062fea22cfe01d466dee83f56b3ed40c89bdcbca671bafeba3fe86b92/supabase-2.18.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "99d23b135af55dd5788bd47875bb81f99c870054b990c030e51fd641a61b10b5",
"md5": "4bb6e9d9df3f77b878221c07dc670225",
"sha256": "205787b1fbb43d6bc997c06fe3a56137336d885a1b56ec10f0012f2a2905285d"
},
"downloads": -1,
"filename": "supabase-2.18.1.tar.gz",
"has_sig": false,
"md5_digest": "4bb6e9d9df3f77b878221c07dc670225",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 11549,
"upload_time": "2025-08-12T19:02:27",
"upload_time_iso_8601": "2025-08-12T19:02:27.852309Z",
"url": "https://files.pythonhosted.org/packages/99/d2/3b135af55dd5788bd47875bb81f99c870054b990c030e51fd641a61b10b5/supabase-2.18.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 19:02:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "supabase",
"github_project": "supabase-py",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "supabase"
}
JSON
