Collect package dependencies in a new optional dependency called runner

docs/api/conf.py

@@ -179,11 +179,6 @@ autodoc_mock_imports = [
     "google.protobuf.runtime_version",
     "google.protobuf.symbol_database",
     "google.protobuf.internal.builder",
-    # Runner
-    "pipecat_ai_small_webrtc_prebuilt",
-    "pipecat_ai_small_webrtc_prebuilt.frontend",
-    "uvicorn",
-    "python_dotenv",
 ]
 
 # HTML output settings

docs/api/requirements.txt

@@ -41,10 +41,10 @@ pipecat-ai[noisereduce]
 pipecat-ai[openai]
 # pipecat-ai[openpipe]
 # pipecat-ai[playht] # Mocked due to grpcio conflict with riva
-pipecat-ai[pipecatcloud]
 pipecat-ai[qwen]
 pipecat-ai[remote-smart-turn]
 # pipecat-ai[riva] # Mocked
+pipecat-ai[runner]
 pipecat-ai[sambanova]
 pipecat-ai[silero]
 pipecat-ai[simli]

examples/quickstart/requirements.txt

@@ -1,3 +1,2 @@
-pipecat-ai[webrtc,silero,deepgram,openai,cartesia]
+pipecat-ai[webrtc,silero,deepgram,openai,cartesia,runner]
-pipecat-ai-small-webrtc-prebuilt
+pipecat-ai-small-webrtc-prebuilt
-python-dotenv

examples/runner-examples/requirements.txt

@@ -1,4 +1 @@
-pipecatcloud
+pipecat-ai[openai,daily,deepgram,cartesia,silero,webrtc,websocket,runner]
-pipecat-ai[openai,daily,deepgram,cartesia,silero,webrtc,websocket]
-python-dotenv
-pipecat-ai-small-webrtc-prebuilt

pyproject.toml

@@ -86,6 +86,7 @@ playht = [ "pyht>=0.1.6", "websockets>=13.1,<15.0" ]
 qwen = []
 rime = [ "websockets>=13.1,<15.0" ]
 riva = [ "nvidia-riva-client~=2.21.1" ]
+runner = [ "python-dotenv>=1.0.0,<2.0.0", "uvicorn>=0.32.0,<1.0.0", "fastapi>=0.115.6,<0.117.0", "pipecatcloud>=0.2.0", "pipecat-ai-small-webrtc-prebuilt>=1.0.0"]
 sambanova = []
 sentry = [ "sentry-sdk~=2.23.1" ]
 local-smart-turn = [ "coremltools>=8.0", "transformers", "torch~=2.5.0", "torchaudio~=2.5.0" ]

src/pipecat/runner/cloud.py

@@ -11,11 +11,9 @@ structured for Pipecat Cloud deployment. The runner enables you to run Pipecat
 bots locally or deployed without requiring any code changes. It supports
 multiple transport types and handles room/token management automatically.
 
-It requires the `pipecatcloud` package for proper session argument types.
-
 Install with::
 
-    pip install pipecat-ai[pipecatcloud]
+    pip install pipecat-ai[runner]
 
 All bots must implement a `bot(session_args)` async function as the entry point.
 The server automatically discovers and executes this function when connections
@@ -73,19 +71,27 @@ from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from typing import Any, Dict, Optional
 
-import uvicorn
-from dotenv import load_dotenv
-from fastapi import BackgroundTasks, FastAPI, WebSocket
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import HTMLResponse, RedirectResponse
 from loguru import logger
 
+try:
+    import uvicorn
+    from dotenv import load_dotenv
+    from fastapi import BackgroundTasks, FastAPI, WebSocket
+    from fastapi.middleware.cors import CORSMiddleware
+    from fastapi.responses import HTMLResponse, RedirectResponse
+except ImportError as e:
+    logger.error(f"Runner dependencies not available: {e}")
+    logger.error("To use Pipecat runners, install with: pip install pipecat-ai[runner]")
+    raise ImportError(
+        "Runner dependencies required. Install with: pip install pipecat-ai[runner]"
+    ) from e
+
 try:
     from pipecatcloud.agent import DailySessionArguments, WebSocketSessionArguments
 except ImportError:
     raise ImportError(
         "pipecatcloud package is required for cloud-compatible bots. "
-        "Install with: pip install pipecat-ai[pipecatcloud]"
+        "Install with: pip install pipecat-ai[runner]"
     )
 
 

src/pipecat/runner/local.py

@@ -10,6 +10,10 @@ This module provides a simplified runner for local development and testing.
 It supports direct function execution without requiring the structured `bot()`
 function pattern needed for cloud deployment.
 
+Install dependencies with::
+
+    pip install pipecat-ai[runner]
+
 Supported transports:
 
 - Daily - Uses environment variables or arguments for room/token
@@ -46,14 +50,22 @@ import sys
 from contextlib import asynccontextmanager
 from typing import Callable, Dict, Mapping, Optional
 
-import aiohttp
-import uvicorn
-from dotenv import load_dotenv
-from fastapi import BackgroundTasks, FastAPI, WebSocket
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import HTMLResponse, RedirectResponse
 from loguru import logger
 
+try:
+    import aiohttp
+    import uvicorn
+    from dotenv import load_dotenv
+    from fastapi import BackgroundTasks, FastAPI, WebSocket
+    from fastapi.middleware.cors import CORSMiddleware
+    from fastapi.responses import HTMLResponse, RedirectResponse
+except ImportError as e:
+    logger.error(f"Runner dependencies not available: {e}")
+    logger.error("To use Pipecat runners, install with: pip install pipecat-ai[runner]")
+    raise ImportError(
+        "Runner dependencies required. Install with: pip install pipecat-ai[runner]"
+    ) from e
+
 load_dotenv(override=True)