RunPod Python SDK

1.7.9 · active · verified Tue Mar 17

Official Python SDK and serverless worker framework for the RunPod cloud GPU platform. Provides tools for creating serverless endpoint workers, managing pods, and interacting with the RunPod API. Used both as a client library and as the runtime framework inside serverless containers.

Warnings

gotcha The handler function must return a dict or a generator. Returning a plain string will cause the worker to fail silently or produce malformed output.
Fix: Always return a dict like {"output": result} from your handler.
gotcha event['input'] is the actual user payload. The top-level event dict contains metadata (id, etc.). Accessing event['prompt'] directly instead of event['input']['prompt'] is a common mistake.
Fix: Access user data via event['input'], not event directly.
breaking Generator (streaming) handlers must yield dicts, not strings. The output format changed in 1.x to require structured yields.
Fix: yield {"output": chunk} in generator handlers, not yield chunk.
gotcha runpod.serverless.start() blocks forever waiting for jobs. It must be the last call in your script. Code after it will never execute.
Fix: Place all initialization (model loading, etc.) before runpod.serverless.start().
gotcha Setting runpod.api_key is required before any API management calls (get_pods, create_pod, etc.). Without it, calls raise an authentication error.
Fix: runpod.api_key = os.environ.get('RUNPOD_API_KEY', '') before making API calls.
gotcha The refresh_worker option in the handler config causes the worker container to restart after every job. This is useful for debugging but causes cold starts in production.
Fix: Set 'refresh_worker': False (or omit it) in production to keep the worker warm between jobs.

Install

pip install runpod Python

Imports

runpod
```
import runpod
```
The main module. Used for both serverless handler registration and API client access.
runpod.serverless.start
```
import runpod
runpod.serverless.start({"handler": my_handler})
```
The start function lives under runpod.serverless, not the top-level module.

Quickstart

Minimal serverless handler that processes an input prompt. The API client section (commented) shows pod management.

import runpod
import os

# --- Serverless Handler Example ---
def handler(event):
    """Serverless handler function."""
    prompt = event['input'].get('prompt', 'Hello!')
    return {"output": f"Processed: {prompt}"}

runpod.serverless.start({"handler": handler})

# --- API Client Example (run separately) ---
# runpod.api_key = os.environ.get('RUNPOD_API_KEY', '')
# pods = runpod.get_pods()
# print(pods)

view raw JSON →