{"id":101,"library":"vercel","title":"Vercel Python SDK","description":"Official Vercel Python SDK. Current version is 0.4.0 (Feb 2026), released as beta Oct 2025. PyPI package is 'vercel', imports as 'vercel'. SDK only covers Blob, Sandbox, Runtime Cache, and OIDC — it does NOT wrap the Vercel REST API (deployments, projects, domains). Five competing PyPI packages exist for Vercel-related Python work: vercel (official), vercel-sdk (official alias), vercel_blob (community), vercel_storage (community), vercelpy (community). Most tutorials predate the official SDK and use community packages.","status":"active","version":"0.4.0","language":"python","source_language":"en","source_url":"https://github.com/vercel/vercel-py","tags":["vercel","blob","storage","serverless","cdn","deployment","python"],"install":[{"cmd":"pip install vercel","lang":"bash","label":"Python (official SDK — Blob, Sandbox, Cache, OIDC)"},{"cmd":"pip install vercel-sdk","lang":"bash","label":"Python (official alias — same package, different PyPI name)"}],"dependencies":[{"reason":"HTTP client. Auto-installed.","package":"httpx","optional":false}],"imports":[{"note":"vercel_blob is a community package predating the official SDK. Both exist on PyPI. The official SDK uses 'from vercel.blob import BlobClient'. vercel_blob has a different API shape.","wrong":"import vercel_blob","symbol":"BlobClient","correct":"from vercel.blob import BlobClient"},{"note":"vercel-sdk and vercel are the same official package. Both install to the same 'vercel' import namespace.","wrong":"from vercel_sdk.blob import AsyncBlobClient","symbol":"AsyncBlobClient","correct":"from vercel.blob import AsyncBlobClient"}],"quickstart":{"code":"import os\nfrom vercel.blob import BlobClient\n\n# Requires BLOB_READ_WRITE_TOKEN env var\nclient = BlobClient()  # reads BLOB_READ_WRITE_TOKEN automatically\n\n# Upload\nuploaded = client.put(\n    'assets/hello.txt',\n    b'hello from python',\n    access='public',\n    content_type='text/plain',\n)\nprint(uploaded.url)\n\n# List\nlisting = client.list_objects(prefix='assets/')\nfor blob in listing.blobs:\n    print(blob.url)\n\n# Download and delete\ncontent = client.get(uploaded.url)\nclient.delete([uploaded.url])\n\n# Runtime Cache\nfrom vercel.cache import get_cache\ncache = get_cache(namespace='my-app')\ncache.set('key', {'value': 42}, {'ttl': 60, 'tags': ['my-tag']})\nresult = cache.get('key')  # dict or None\ncache.expire_tag('my-tag')","lang":"python","description":"Blob upload/list/delete and Runtime Cache using official vercel SDK v0.4.x."},"warnings":[{"fix":"For REST API management (deployments, projects), use direct HTTP calls to api.vercel.com with a VERCEL_TOKEN. No official Python wrapper for the management API exists.","message":"The official 'vercel' SDK (pip install vercel) does NOT cover the Vercel REST API (deployments, projects, teams, domains). It only covers Blob, Sandbox, Runtime Cache, and OIDC. Agents expecting deployment management will get ImportError or AttributeError.","severity":"breaking","affected_versions":"all"},{"fix":"For new projects use 'pip install vercel' (official). Check with 'pip show vercel' to confirm official package is installed (author: Vercel).","message":"Five competing PyPI packages for Vercel Python work: 'vercel' (official), 'vercel-sdk' (official alias), 'vercel_blob' (community), 'vercel_storage' (community), 'vercelpy' (community). They have incompatible APIs. Installing the wrong one fails silently with wrong import paths.","severity":"breaking","affected_versions":"all"},{"fix":"Set BLOB_READ_WRITE_TOKEN env var, or pass token explicitly: BlobClient(token='vercel_blob_rw_...'). Token is obtained from Vercel Dashboard → Storage → your blob store → Tokens.","message":"BlobClient() raises an exception if BLOB_READ_WRITE_TOKEN env var is not set and no token is passed. Error is not a standard Python exception — it's a custom BlobError with no obvious message about which env var is missing.","severity":"breaking","affected_versions":"all"},{"fix":"Set RUNTIME_CACHE_ENDPOINT and RUNTIME_CACHE_HEADERS env vars to use real cache. Check SUSPENSE_CACHE_DEBUG=true to verify which backend is active.","message":"Runtime Cache only works inside Vercel Functions at runtime. Outside of Vercel (local dev, CI), it falls back to an in-memory cache silently. Code that works locally may behave differently in production if it relies on tag-based invalidation.","severity":"breaking","affected_versions":"all"},{"fix":"For local dev: run 'vercel env pull' to populate .env with OIDC credentials. Or pass VERCEL_TOKEN + VERCEL_TEAM_ID + VERCEL_PROJECT_ID explicitly.","message":"Sandbox requires VERCEL_OIDC_TOKEN (injected automatically in Vercel Functions) or a valid Vercel CLI login locally. Running Sandbox code outside Vercel without CLI credentials raises authentication errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Pass add_random_suffix=False to client.put() to disable. Note: disabling it means re-uploading the same path overwrites the previous file.","message":"Blob put() adds a random suffix to filenames by default (add_random_suffix=True). Files uploaded as 'photo.jpg' are stored as 'photo-AbCdEfGh.jpg'. The returned URL reflects the actual stored name.","severity":"gotcha","affected_versions":"all"},{"fix":"Pin: vercel==0.4.0 in requirements.txt until stable v1.0 release.","message":"SDK is in beta. Breaking changes between minor versions have occurred without major version bump. Official docs warn to pin the version.","severity":"gotcha","affected_versions":"< 1.0"},{"fix":"Ensure your Python interpreter is version 3.10 or newer. Upgrade your environment's Python version if necessary.","message":"The 'vercel' SDK (e.g., version 0.3.4) uses Python 3.10+ union type syntax (e.g., `int | None`) in its type hints. When run on Python 3.9 or older interpreters, this results in a `TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'` during module import.","severity":"breaking","affected_versions":"0.3.4+ on < 3.10"}],"env_vars":null,"last_verified":"2026-05-12T08:06:29.054Z","next_check":"2026-06-17T00:00:00.000Z","problems":[{"fix":"pip install vercel","cause":"The official Vercel Python SDK package has not been installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'vercel'"},{"fix":"To manage deployments, projects, or domains, use the Vercel CLI or interact with the Vercel REST API directly via an HTTP client.","cause":"The official Vercel Python SDK (version 0.4.0) currently does not provide functionality for Vercel deployments, projects, or other REST API operations.","error":"AttributeError: module 'vercel' has no attribute 'deploy'"},{"fix":"Set the 'VERCEL_BLOB_READ_WRITE_TOKEN' environment variable in your development environment or deployment configuration:\n\nexport VERCEL_BLOB_READ_WRITE_TOKEN=\"your_token_here\"\n\nAlternatively, pass the token explicitly:\nimport os\nfrom vercel.blob import blob\nclient = blob.client(token=os.getenv(\"VERCEL_BLOB_READ_WRITE_TOKEN\"))","cause":"The Vercel Blob client requires the 'VERCEL_BLOB_READ_WRITE_TOKEN' environment variable to be set for authentication, which was not found.","error":"vercel.exceptions.VercelBlobAuthenticationError: VERCEL_BLOB_READ_WRITE_TOKEN not found in environment variables."},{"fix":"If you intend to use the official SDK, ensure you have 'vercel' installed via 'pip install vercel' and import as 'from vercel.blob import blob'.","cause":"You are attempting to import from a community-maintained package 'vercel_blob' which is distinct from the official Vercel SDK's 'vercel.blob' module.","error":"ModuleNotFoundError: No module named 'vercel_blob'"},{"fix":"Import the 'blob' object and then use its 'client()' method to get an authenticated client instance:\nfrom vercel.blob import blob\nclient = blob.client()\n# Example usage: client.put(\"my-file.txt\", \"hello world\")","cause":"You are attempting to access a non-existent 'Blob' class or object directly from the 'vercel.blob' module; the Blob client is instantiated via 'blob.client()'.","error":"AttributeError: module 'vercel.blob' has no attribute 'Blob'"}],"ecosystem":"pypi","meta_description":null,"install_score":90,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.36,"mem_mb":10,"disk_size":"35.3M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.25,"mem_mb":8.7,"disk_size":"35.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.27,"mem_mb":10,"disk_size":"35M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":8.7,"disk_size":"35M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.55,"mem_mb":11.3,"disk_size":"38.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.42,"mem_mb":9.9,"disk_size":"38.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":11.3,"disk_size":"39M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.33,"mem_mb":9.9,"disk_size":"39M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.69,"mem_mb":11.3,"disk_size":"30.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.54,"mem_mb":12.5,"disk_size":"30.9M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.63,"mem_mb":11.3,"disk_size":"31M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.54,"mem_mb":12.5,"disk_size":"31M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.65,"mem_mb":11.4,"disk_size":"30.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.56,"mem_mb":12.9,"disk_size":"30.6M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.59,"mem_mb":11.4,"disk_size":"30M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.52,"mem_mb":12.9,"disk_size":"31M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}