RunPod Python SDK

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

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.

pip install runpod

Common errors

error AttributeError: module 'runpod' has no attribute 'serverless' ↓

cause The installed 'runpod' library version is outdated and does not include the 'serverless' submodule, which is essential for developing RunPod serverless workers.

fix

Upgrade 'runpod' to the latest version: pip install --upgrade runpod

error runpod.exceptions.RunPodAuthError: Unauthorized: Invalid API key. ↓

cause The provided RunPod API key is either missing, incorrect, or lacks the necessary permissions for the requested API operation.

fix

Ensure the 'RUNPOD_API_KEY' environment variable is set with a valid API key from your RunPod account, or pass it directly when interacting with the API (e.g., runpod.api_key = "your_api_key").

error ConnectionError: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused')) ↓

cause The 'runpod.serverless' worker failed to start correctly or crashed, preventing it from listening for requests on the expected port (default 8000), or the client is attempting to connect to the wrong address/port.

fix

Debug the 'handler' function for unhandled exceptions during startup. Ensure 'runpod.serverless.start()' is called and the worker is configured to listen on port 8000. For local testing, verify the client connects to http://localhost:8000.

error ModuleNotFoundError: No module named 'runpod.serverless' ↓

cause The 'runpod' library, specifically the 'runpod.serverless' submodule, is not installed or accessible within the current Python environment or container.

fix

Install 'runpod' using pip install runpod and ensure it is included in your 'requirements.txt' for containerized deployments.

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.

gotcha Running pip as the 'root' user can lead to broken permissions and conflicting behavior with the system package manager. This can cause system instability or unexpected behavior in your application. ↓

fix It is recommended to use virtual environments for dependency management or run pip with a non-root user. If building a Docker image, consider adding a non-root user and switching to it before installing dependencies (e.g., `RUN useradd -m appuser && su appuser`). Alternatively, use the `--user` flag with pip to install packages to the user's home directory.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 3.19s 160.0M

3.10 slim (glibc) - - 2.75s 165M

3.11 alpine (musl) - - 3.62s 173.2M

3.11 slim (glibc) - - 3.29s 179M

3.12 alpine (musl) - - 3.83s 165.0M

3.12 slim (glibc) - - 3.87s 172M

3.13 alpine (musl) - - 3.76s 164.5M

3.13 slim (glibc) - - 3.85s 171M

3.9 alpine (musl) - - 2.85s 164.7M

3.9 slim (glibc) - - 2.87s 167M

Imports

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

Quickstart stale last tested: 2026-05-12

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)