runpod

library1.12.0pypypi✓ verified 26d ago

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.

llm-agents ai-ml aws

pip install runpod

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · RUNPOD

runpod

llm-agentspythonv1.12.0

Install

18.1s avg

Import

3006ms

Disk

178MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.12.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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 3.056s · 172.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 18.1s · import 2.956s · 178MB

178MB installed

● package 178MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

✗ from runpod import start

The start function lives under runpod.serverless, not the top-level module.

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)

runpod --version

Debug

Known issues

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

affects: all

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

affects: all

breakingGenerator (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.

affects: >= 1.0.0

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

affects: all

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

affects: all

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

affects: all

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

affects: all

Errors

Common errors & fixes

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

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`

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

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"`).

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

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

ModuleNotFoundError: No module named 'runpod.serverless'

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.

Upgrade

Version history

1.12.0latest on PyPI · released Aug 10, 2026

Audit

Dependencies

aiohttprequiredUsed internally for async HTTP requests to the RunPod API.

requestsrequiredUsed for synchronous HTTP requests to the RunPod API.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/runpod/runpod-python ↗

packagehttps://pypi.org/project/runpod/ ↗

homepagehttps://runpod.io ↗

docshttps://docs.runpod.io ↗

changeloghttps://github.com/runpod/runpod-python/blob/main/CHANGELOG.md ↗