Install & Compatibility
Where this runs
tested against v2.31.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.662s · 35.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.1s · import 0.618s · 35MB
34MB installed
● package 34MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AsyncStorageClient
✓ from storage3 import AsyncStorageClient
For asynchronous operations with Supabase Storage.
SyncStorageClient
✓ from storage3 import SyncStorageClient
For synchronous operations with Supabase Storage (available in recent versions).
This quickstart demonstrates how to initialize the `AsyncStorageClient`, list existing buckets (and optionally create one), upload a file, list files within a bucket, download a file, and finally delete the uploaded file. Ensure you have your Supabase project URL and API key set as environment variables (SUPABASE_URL and SUPABASE_KEY) for authentication.
import os
from storage3 import AsyncStorageClient
import asyncio
# Replace with your Supabase project URL and API Key
SUPABASE_URL = os.environ.get('SUPABASE_URL', 'https://your-project-id.supabase.co/storage/v1')
SUPABASE_KEY = os.environ.get('SUPABASE_KEY', 'your_anon_public_key')
# Headers are required for authentication
HEADERS = {"apiKey": SUPABASE_KEY, "Authorization": f"Bearer {SUPABASE_KEY}"}
async def main():
storage_client = AsyncStorageClient(SUPABASE_URL, HEADERS)
print("Listing buckets...")
try:
buckets = await storage_client.list_buckets()
if buckets:
print(f"Found {len(buckets)} bucket(s): {[b['name'] for b in buckets]}")
else:
print("No buckets found. Attempting to create one...")
new_bucket = await storage_client.create_bucket('my-test-bucket-py', {'public': True})
print(f"Created bucket: {new_bucket['name']}")
buckets = [new_bucket]
if buckets:
bucket_name = buckets[0]['name']
print(f"Using bucket: {bucket_name}")
# Example: Uploading a dummy file (requires a file_object, e.g., from an open file)
# For a real scenario, replace `b'Hello, Supabase Storage!'` with actual file data
file_content = b'Hello, Supabase Storage from Python!'
file_name = 'hello_world.txt'
print(f"Uploading file '{file_name}' to bucket '{bucket_name}'...")
upload_response = await storage_client.from_(bucket_name).upload(
f'public/{file_name}',
file_content,
{'content-type': 'text/plain'}
)
print(f"Upload successful: {upload_response}")
# Example: Listing files in the bucket
print(f"Listing files in bucket '{bucket_name}'...")
files = await storage_client.from_(bucket_name).list(path='public/')
print(f"Files in bucket '{bucket_name}': {[f['name'] for f in files]}")
# Example: Downloading the file
print(f"Downloading file '{file_name}' from bucket '{bucket_name}'...")
downloaded_data = await storage_client.from_(bucket_name).download(f'public/{file_name}')
print(f"Downloaded content: {downloaded_data.decode()}")
# Example: Deleting the file
print(f"Deleting file '{file_name}' from bucket '{bucket_name}'...")
delete_response = await storage_client.from_(bucket_name).remove([f'public/{file_name}'])
print(f"Delete successful: {delete_response}")
except Exception as e:
print(f"An error occurred: {e}")
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
breakingA minor breaking change related to `supabase_auth` affected `storage3` version `2.24.0`, which was subsequently yanked from PyPI. If you encounter authentication issues, especially around this version range, consider using a different version of `storage3` or consult the `supabase-py` changelog for compatible `gotrue` (Supabase Auth) client versions.fixAvoid `storage3` version `2.24.0`. Ensure compatibility with your `supabase-py` and `gotrue` client versions. Upgrade to the latest stable release of `storage3` and `supabase-py`.
affects: 2.24.0 (yanked), potentially nearby versions
gotchaWhen uploading files, it is crucial to explicitly set the `content-type` within the `file_options` argument (e.g., `{'content-type': 'image/png'}`). If omitted, files will default to `text/plain` MIME type, which can lead to incorrect serving or handling by browsers and applications.fixAlways pass a `file_options` dictionary with the correct `content-type` for your uploaded file: `await storage_client.from_('bucket').upload('path/to/file.ext', file_object, {'content-type': 'your/mimetype'})`. affects: All versions
gotchaSupabase Storage access is governed by Row Level Security (RLS) policies defined within your Supabase project. Improperly configured RLS on the `objects` table (and sometimes `buckets` table) is a common source of 'permission denied' errors when performing operations like uploading, downloading, or listing files.fixEnsure that appropriate RLS policies are created and enabled in your Supabase Dashboard for the `storage.objects` and `storage.buckets` tables, granting `SELECT`, `INSERT`, `UPDATE`, or `DELETE` permissions as required by your application's logic.
affects: All versions
gotchaThe `storage-py` repository, which contains `storage3`, has been moved into the main `supabase-py` monorepo. While `storage3` continues to be released as a standalone package, its development and issue tracking are now integrated with the broader Supabase Python client.fixFor the latest development information, contributions, or issue reporting, refer to the main `supabase-py` monorepo's issues and pull requests, rather than solely the `storage-py` repository.
affects: All versions after migration
breakingA `TLS/SSL connection has been closed (EOF)` error can occur when the client (your application) fails to establish or maintain a secure connection with the Supabase Storage endpoint. This is often observed with older Python versions (such as 3.9 or earlier) due to potential incompatibilities with modern TLS protocols or outdated underlying SSL libraries in the environment.fixUpgrade your Python environment to 3.10 or newer. Ensure your system's SSL/TLS libraries are up-to-date. Verify network connectivity to the Supabase Storage endpoint and check for any intermediate proxies or firewalls that might be interfering with TLS handshakes.
affects: All versions when run in environments with older Python versions (e.g., 3.9 and below) or outdated SSL libraries.
gotchaThe client failed to connect to the Supabase Storage service, resulting in a 'Name does not resolve' error. This typically indicates an incorrect or unreachable `SUPABASE_URL` or `SUPABASE_STORAGE_URL` environment variable, or an issue with DNS resolution. This prevents any interaction with the storage backend.fixEnsure your `SUPABASE_URL` or `SUPABASE_STORAGE_URL` environment variable is correctly set and accessible from your environment, or explicitly pass the correct storage URL to the client. Verify that the hostname specified in the URL is correct and resolvable via DNS.
affects: All versions
Upgrade
Version history
2.31.0latest on PyPI · released Jun 4, 2026
Audit
Dependencies
No dependency data recorded yet.