{"id":70,"library":"runpod","title":"RunPod Python SDK","description":"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.","status":"active","version":"1.7.9","language":"python","source_language":"en","source_url":"https://github.com/runpod/runpod-python","tags":["runpod","gpu","serverless","cloud","ml","inference","python"],"install":[{"cmd":"pip install runpod","lang":"bash","label":"Python"}],"dependencies":[{"reason":"Used internally for async HTTP requests to the RunPod API.","package":"aiohttp","optional":false},{"reason":"Used for synchronous HTTP requests to the RunPod API.","package":"requests","optional":false}],"imports":[{"note":"The main module. Used for both serverless handler registration and API client access.","symbol":"runpod","correct":"import runpod"},{"note":"The start function lives under runpod.serverless, not the top-level module.","wrong":"from runpod import start","symbol":"runpod.serverless.start","correct":"import runpod\nrunpod.serverless.start({\"handler\": my_handler})"}],"quickstart":{"code":"import runpod\nimport os\n\n# --- Serverless Handler Example ---\ndef handler(event):\n    \"\"\"Serverless handler function.\"\"\"\n    prompt = event['input'].get('prompt', 'Hello!')\n    return {\"output\": f\"Processed: {prompt}\"}\n\nrunpod.serverless.start({\"handler\": handler})\n\n# --- API Client Example (run separately) ---\n# runpod.api_key = os.environ.get('RUNPOD_API_KEY', '')\n# pods = runpod.get_pods()\n# print(pods)","lang":"python","description":"Minimal serverless handler that processes an input prompt. The API client section (commented) shows pod management."},"warnings":[{"fix":"Always return a dict like {\"output\": result} from your handler.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Access user data via event['input'], not event directly.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"yield {\"output\": chunk} in generator handlers, not yield chunk.","message":"Generator (streaming) handlers must yield dicts, not strings. The output format changed in 1.x to require structured yields.","severity":"breaking","affected_versions":">= 1.0.0"},{"fix":"Place all initialization (model loading, etc.) before runpod.serverless.start().","message":"runpod.serverless.start() blocks forever waiting for jobs. It must be the last call in your script. Code after it will never execute.","severity":"gotcha","affected_versions":"all"},{"fix":"runpod.api_key = os.environ.get('RUNPOD_API_KEY', '') before making API calls.","message":"Setting runpod.api_key is required before any API management calls (get_pods, create_pod, etc.). Without it, calls raise an authentication error.","severity":"gotcha","affected_versions":"all"},{"fix":"Set 'refresh_worker': False (or omit it) in production to keep the worker warm between jobs.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":[{"name":"RUNPOD_API_KEY","required":true,"description":"API key for authenticating with RunPod's management API. Required for pod/endpoint management, not needed inside a serverless handler at runtime."}],"last_verified":"2026-05-12T06:38:07.166Z","next_check":"2026-06-17T00:00:00.000Z","problems":[{"fix":"Upgrade 'runpod' to the latest version: `pip install --upgrade runpod`","cause":"The installed 'runpod' library version is outdated and does not include the 'serverless' submodule, which is essential for developing RunPod serverless workers.","error":"AttributeError: module 'runpod' has no attribute 'serverless'"},{"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\"`).","cause":"The provided RunPod API key is either missing, incorrect, or lacks the necessary permissions for the requested API operation.","error":"runpod.exceptions.RunPodAuthError: Unauthorized: Invalid API key."},{"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`.","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.","error":"ConnectionError: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused'))"},{"fix":"Install 'runpod' using `pip install runpod` and ensure it is included in your 'requirements.txt' for containerized deployments.","cause":"The 'runpod' library, specifically the 'runpod.serverless' submodule, is not installed or accessible within the current Python environment or container.","error":"ModuleNotFoundError: No module named 'runpod.serverless'"}],"ecosystem":"pypi","meta_description":null,"install_score":95,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.19,"mem_mb":27.4,"disk_size":"160.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.75,"mem_mb":27.4,"disk_size":"165M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.62,"mem_mb":30,"disk_size":"173.2M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.29,"mem_mb":30.2,"disk_size":"179M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.83,"mem_mb":29.9,"disk_size":"165.0M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.87,"mem_mb":30,"disk_size":"172M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.76,"mem_mb":30.7,"disk_size":"164.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.85,"mem_mb":30.7,"disk_size":"171M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.85,"mem_mb":24.8,"disk_size":"164.7M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.87,"mem_mb":24.8,"disk_size":"167M"}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}