Vercel Python SDK

0.4.0 verified Tue May 12 auth: no python install: verified quickstart: stale

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.

pip install vercel

Common errors

error ModuleNotFoundError: No module named 'vercel' ↓

cause The official Vercel Python SDK package has not been installed in your current Python environment.

fix

pip install vercel

error AttributeError: module 'vercel' has no attribute 'deploy' ↓

cause The official Vercel Python SDK (version 0.4.0) currently does not provide functionality for Vercel deployments, projects, or other REST API operations.

fix

To manage deployments, projects, or domains, use the Vercel CLI or interact with the Vercel REST API directly via an HTTP client.

error vercel.exceptions.VercelBlobAuthenticationError: VERCEL_BLOB_READ_WRITE_TOKEN not found in environment variables. ↓

cause The Vercel Blob client requires the 'VERCEL_BLOB_READ_WRITE_TOKEN' environment variable to be set for authentication, which was not found.

fix

Set the 'VERCEL_BLOB_READ_WRITE_TOKEN' environment variable in your development environment or deployment configuration: export VERCEL_BLOB_READ_WRITE_TOKEN="your_token_here" Alternatively, pass the token explicitly: import os from vercel.blob import blob client = blob.client(token=os.getenv("VERCEL_BLOB_READ_WRITE_TOKEN"))

error ModuleNotFoundError: No module named 'vercel_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.

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'.

error AttributeError: module 'vercel.blob' has no attribute 'Blob' ↓

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()'.

fix

Import the 'blob' object and then use its 'client()' method to get an authenticated client instance: from vercel.blob import blob client = blob.client() # Example usage: client.put("my-file.txt", "hello world")

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.

breaking 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. ↓

fix Ensure your Python interpreter is version 3.10 or newer. Upgrade your environment's Python version if necessary.

Install

pip install vercel-sdk

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) vercel - - 0.36s 35.3M

3.10 alpine (musl) vercel-sdk - - 0.25s 35.4M

3.10 slim (glibc) vercel - - 0.27s 35M

3.10 slim (glibc) vercel-sdk - - 0.20s 35M

3.11 alpine (musl) vercel - - 0.55s 38.8M

3.11 alpine (musl) vercel-sdk - - 0.42s 38.9M

3.11 slim (glibc) vercel - - 0.46s 39M

3.11 slim (glibc) vercel-sdk - - 0.33s 39M

3.12 alpine (musl) vercel - - 0.69s 30.8M

3.12 alpine (musl) vercel-sdk - - 0.54s 30.9M

3.12 slim (glibc) vercel - - 0.63s 31M

3.12 slim (glibc) vercel-sdk - - 0.54s 31M

3.13 alpine (musl) vercel - - 0.65s 30.5M

3.13 alpine (musl) vercel-sdk - - 0.56s 30.6M

3.13 slim (glibc) vercel - - 0.59s 30M

3.13 slim (glibc) vercel-sdk - - 0.52s 31M

3.9 alpine (musl) vercel - - - -

3.9 alpine (musl) vercel-sdk - - - -

3.9 slim (glibc) vercel - - - -

3.9 slim (glibc) vercel-sdk - - - -

Imports

BlobClient
wrong
```
import vercel_blob
```
correct
```
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
wrong
```
from vercel_sdk.blob import AsyncBlobClient
```
correct
```
from vercel.blob import AsyncBlobClient
```
vercel-sdk and vercel are the same official package. Both install to the same 'vercel' import namespace.

Quickstart stale last tested: 2026-05-12

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')