Install & Compatibility
Where this runs
tested against v0.10.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.910 runs
installs and imports cleanly · install 0.0s · import 0.402s · 87.3MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.5s · import 0.354s · 40MB
57MB installed
● package 57MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BlobClient
✓ from vercel.blob import BlobClient
✗ import vercel_blob
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
✗ from vercel_sdk.blob import AsyncBlobClient
vercel-sdk and vercel are the same official package. Both install to the same 'vercel' import namespace.
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')
Debug
Known issues
breakingThe 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.fixFor 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.
affects: all
breakingFive 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.fixFor new projects use 'pip install vercel' (official). Check with 'pip show vercel' to confirm official package is installed (author: Vercel).
affects: all
breakingBlobClient() 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.fixSet 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.
affects: all
breakingRuntime 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.fixSet RUNTIME_CACHE_ENDPOINT and RUNTIME_CACHE_HEADERS env vars to use real cache. Check SUSPENSE_CACHE_DEBUG=true to verify which backend is active.
affects: all
gotchaSandbox 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.fixFor local dev: run 'vercel env pull' to populate .env with OIDC credentials. Or pass VERCEL_TOKEN + VERCEL_TEAM_ID + VERCEL_PROJECT_ID explicitly.
affects: all
gotchaBlob 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.fixPass add_random_suffix=False to client.put() to disable. Note: disabling it means re-uploading the same path overwrites the previous file.
affects: all
gotchaSDK is in beta. Breaking changes between minor versions have occurred without major version bump. Official docs warn to pin the version.fixPin: vercel==0.4.0 in requirements.txt until stable v1.0 release.
affects: < 1.0
breakingThe '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.fixEnsure your Python interpreter is version 3.10 or newer. Upgrade your environment's Python version if necessary.
affects: 0.3.4+ on < 3.10
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'vercel'
The official Vercel Python SDK package has not been installed in your current Python environment.
AttributeError: module 'vercel' has no attribute 'deploy'
The official Vercel Python SDK (version 0.4.0) currently does not provide functionality for Vercel deployments, projects, or other REST API operations.
fixTo manage deployments, projects, or domains, use the Vercel CLI or interact with the Vercel REST API directly via an HTTP client.
vercel.exceptions.VercelBlobAuthenticationError: VERCEL_BLOB_READ_WRITE_TOKEN not found in environment variables.
The Vercel Blob client requires the 'VERCEL_BLOB_READ_WRITE_TOKEN' environment variable to be set for authentication, which was not found.
fixSet 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")) ModuleNotFoundError: No module named 'vercel_blob'
You are attempting to import from a community-maintained package 'vercel_blob' which is distinct from the official Vercel SDK's 'vercel.blob' module.
fixIf you intend to use the official SDK, ensure you have 'vercel' installed via 'pip install vercel' and import as 'from vercel.blob import blob'.
AttributeError: module 'vercel.blob' has no attribute 'Blob'
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()'.
fixImport 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") Upgrade
Version history
0.10.0latest on PyPI · released Aug 12, 2026
Audit
Dependencies
httpxrequiredHTTP client. Auto-installed.