{"library":"storage3","title":"Supabase Storage client for Python","description":"storage3 is the Python client library for interacting with Supabase Storage. It allows developers to manage files and folders within Supabase buckets. As of version 2.28.3, it provides both synchronous and asynchronous APIs for seamless integration. The library is actively maintained by Supabase, with frequent releases to add features and address issues.","status":"active","version":"2.28.3","language":"en","source_language":"en","source_url":"https://github.com/supabase/storage-py","tags":["Supabase","Storage","Cloud Storage","API Client","Files","Buckets","Asynchronous","Synchronous"],"install":[{"cmd":"pip install storage3","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"For asynchronous operations with Supabase Storage.","symbol":"AsyncStorageClient","correct":"from storage3 import AsyncStorageClient"},{"note":"For synchronous operations with Supabase Storage (available in recent versions).","symbol":"SyncStorageClient","correct":"from storage3 import SyncStorageClient"}],"quickstart":{"code":"import os\nfrom storage3 import AsyncStorageClient\nimport asyncio\n\n# Replace with your Supabase project URL and API Key\nSUPABASE_URL = os.environ.get('SUPABASE_URL', 'https://your-project-id.supabase.co/storage/v1')\nSUPABASE_KEY = os.environ.get('SUPABASE_KEY', 'your_anon_public_key')\n\n# Headers are required for authentication\nHEADERS = {\"apiKey\": SUPABASE_KEY, \"Authorization\": f\"Bearer {SUPABASE_KEY}\"}\n\nasync def main():\n    storage_client = AsyncStorageClient(SUPABASE_URL, HEADERS)\n    \n    print(\"Listing buckets...\")\n    try:\n        buckets = await storage_client.list_buckets()\n        if buckets:\n            print(f\"Found {len(buckets)} bucket(s): {[b['name'] for b in buckets]}\")\n        else:\n            print(\"No buckets found. Attempting to create one...\")\n            new_bucket = await storage_client.create_bucket('my-test-bucket-py', {'public': True})\n            print(f\"Created bucket: {new_bucket['name']}\")\n            buckets = [new_bucket]\n\n        if buckets:\n            bucket_name = buckets[0]['name']\n            print(f\"Using bucket: {bucket_name}\")\n\n            # Example: Uploading a dummy file (requires a file_object, e.g., from an open file)\n            # For a real scenario, replace `b'Hello, Supabase Storage!'` with actual file data\n            file_content = b'Hello, Supabase Storage from Python!'\n            file_name = 'hello_world.txt'\n            \n            print(f\"Uploading file '{file_name}' to bucket '{bucket_name}'...\")\n            upload_response = await storage_client.from_(bucket_name).upload(\n                f'public/{file_name}', \n                file_content,\n                {'content-type': 'text/plain'}\n            )\n            print(f\"Upload successful: {upload_response}\")\n            \n            # Example: Listing files in the bucket\n            print(f\"Listing files in bucket '{bucket_name}'...\")\n            files = await storage_client.from_(bucket_name).list(path='public/')\n            print(f\"Files in bucket '{bucket_name}': {[f['name'] for f in files]}\")\n\n            # Example: Downloading the file\n            print(f\"Downloading file '{file_name}' from bucket '{bucket_name}'...\")\n            downloaded_data = await storage_client.from_(bucket_name).download(f'public/{file_name}')\n            print(f\"Downloaded content: {downloaded_data.decode()}\")\n\n            # Example: Deleting the file\n            print(f\"Deleting file '{file_name}' from bucket '{bucket_name}'...\")\n            delete_response = await storage_client.from_(bucket_name).remove([f'public/{file_name}'])\n            print(f\"Delete successful: {delete_response}\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"fix":"Avoid `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`.","message":"A 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.","severity":"breaking","affected_versions":"2.24.0 (yanked), potentially nearby versions"},{"fix":"Always 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'})`.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"Supabase 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For 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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions after migration"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-06T00:00:00.000Z"}