Vercel Python SDK

Warnings

• breaking 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.
  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.
• breaking 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.
  Fix: For new projects use 'pip install vercel' (official). Check with 'pip show vercel' to confirm official package is installed (author: Vercel).
• breaking 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Pass add_random_suffix=False to client.put() to disable. Note: disabling it means re-uploading the same path overwrites the previous file.
• gotcha SDK is in beta. Breaking changes between minor versions have occurred without major version bump. Official docs warn to pin the version.
  Fix: Pin: vercel==0.4.0 in requirements.txt until stable v1.0 release.

Install

• pip install vercel Python (official SDK — Blob, Sandbox, Cache, OIDC)
• pip install vercel-sdk Python (official alias — same package, different PyPI name)

Imports

• BlobClient

  from vercel.blob import BlobClient

  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.
• AsyncBlobClient

  from vercel.blob import AsyncBlobClient

  vercel-sdk and vercel are the same official package. Both install to the same 'vercel' import namespace.

Quickstart

Blob upload/list/delete and Runtime Cache using official vercel SDK v0.4.x.

import os
from vercel.blob import BlobClient

# Requires BLOB_READ_WRITE_TOKEN env var
client = BlobClient()  # reads BLOB_READ_WRITE_TOKEN automatically

# Upload
uploaded = client.put(
    'assets/hello.txt',
    b'hello from python',
    access='public',
    content_type='text/plain',
)
print(uploaded.url)

# List
listing = client.list_objects(prefix='assets/')
for blob in listing.blobs:
    print(blob.url)

# Download and delete
content = client.get(uploaded.url)
client.delete([uploaded.url])

# Runtime Cache
from vercel.cache import get_cache
cache = get_cache(namespace='my-app')
cache.set('key', {'value': 42}, {'ttl': 60, 'tags': ['my-tag']})
result = cache.get('key')  # dict or None
cache.expire_tag('my-tag')