runpod/runpod-python

Runpod | Python Library

A thin, well‑documented Python SDK that lets you talk to Runpod’s cloud platform (GPU‑powered “pods” and serverless endpoints) from your own code. It wraps the Runpod REST v2 API, provides a tiny framework for building serverless workers (custom model inference APIs), and includes helpers for pod lifecycle management.

What it does

Area	Capability
Serverless worker SDK	Write a Python function that processes a job, then start it with `runpod.serverless.start({"handler": my_func})`. The SDK handles health‑checks, optional GPU/volume warm‑caches, and can be run locally for debugging.
REST v2 wrapper	`runpod.Endpoint(id)` gives an object with `.run()` (async) and `.run_sync()` (blocking) methods to invoke a deployed endpoint.
Pod management	Functions like `runpod.create_pod()`, `runpod.get_pods()`, `runpod.stop_pod()`, `runpod.resume_pod()`, `runpod.terminate_pod()` let you spin up, query, and control GPU or CPU pods programmatically.
API‑key handling	Global key via `runpod.api_key` or per‑endpoint key; precedence is documented and thread‑safe.
Utility helpers	`VolumeCache` for warming network‑mounted model caches; fitness‑check decorators to verify GPU, disk space, etc., before a worker starts.

Quick start (serverless worker)

# my_worker.py
import runpod

def is_even(job):
    n = job["input"]["number"]
    if not isinstance(n, int):
        return {"error": "need an integer"}
    return n % 2 == 0

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

Add the script as the container’s entry‑point (Docker CMD or Runpod template) and the function will be exposed as a custom API endpoint.

Quick start (calling an existing endpoint)

import runpod
runpod.api_key = "YOUR_KEY"

ep = runpod.Endpoint("ENDPOINT_ID")
result = ep.run_sync({"text": "hello"})
print(result)   # → model output or status dict

Pod lifecycle example

import runpod
runpod.api_key = "YOUR_KEY"

# create a GPU pod
pod = runpod.create_pod(name="demo", image="runpod/stack", gpu_type="NVIDIA GeForce RTX 4090")
print(pod["id"])

# later…
runpod.stop_pod(pod["id"])   # pause
runpod.resume_pod(pod["id"]) # resume
runpod.terminate_pod(pod["id"]) # delete

Installation

# stable release
pip install runpod   # or: uv add runpod

# latest development version
pip install git+https://github.com/runpod/runpod-python.git

Python 3.10+ is required.

Notable design points

Fitness checks – Decorators (@runpod.serverless.register_fitness_check) run once at worker start; failure aborts the process so the orchestrator can restart a healthy instance.
Network‑volume warm cache – VolumeCache copies a remote volume (e.g., HuggingFace model cache) to local storage on cold start and syncs back on exit, turning multi‑GB downloads into a one‑time cost per endpoint.
Thread‑safe endpoint objects – Each Endpoint stores its own API key, making concurrent requests from multiple threads safe.
Full‑featured pod creation – Supports GPU and CPU pods, custom Docker args, volume mounts, placement constraints, and scaling parameters.

Where to go next?

Docs – https://docs.runpod.io/serverless-ai/custom-apis and the docs/ folder in the repo.
Examples – See the examples/ directory for ready‑made workers and pod scripts.
Community – Join the Discord (link in README) for help, feature requests, and announcements.

In a nutshell: the runpod Python package is the official, production‑grade bridge between your code and Runpod’s GPU cloud, letting you spin up pods, call model endpoints, or ship custom serverless inference APIs with just a few lines of Python.