Installation

pyRPC follows a modular packaging strategy. You only pay for what you use.

Project Setup

Python

Before installing pyRPC, set up a Python virtual environment:

# Create a virtual environment
python -m venv .venv

# Activate it
# macOS / Linux:
source .venv/bin/activate

# Windows:
.venv\Scripts\activate

If you're using uv (recommended), you can initialize a new project:

# Initialize a new uv project (which creates the virtual environment)
uv init

# Or if your project already exists, just create the venv
uv venv

# Activate it
# macOS / Linux:
source .venv/bin/activate

# Windows:
.venv\Scripts\activate

TypeScript / npm

For the frontend client, you'll need a TypeScript project. Create one if you haven't already:

# Create a new TypeScript project
npm init -y
npm install typescript --save-dev
npx tsc --init

The @pyrpc/client package and your framework adapter are installed later via npm when you set up the frontend.

Core Package

The tiny core protocol and runtime. This is always required. Make sure your virtual environment is activated first, then:

# Using uv
uv add pyrpc-core

# Using pip
pip install pyrpc-core

Adapters

Install the adapter for your favorite web framework.

FastAPI

# Using uv
uv add pyrpc-core[fastapi]

# Using pip
pip install pyrpc-core[fastapi]

Flask

# Using uv
uv add pyrpc-core[flask]

# Using pip
pip install pyrpc-core[flask]

Django

# Using uv
uv add pyrpc-core[django]

# Using pip
pip install pyrpc-core[django]

CLI & Code Generation

The pyrpc CLI comes built-in with pyrpc-core - no separate install needed.

Dev Server (Recommended)

The fastest way to get started:

pyrpc dev

On first run, pyrpc dev walks you through setup interactively - backend framework and entry point, client project root, and frontend framework. It creates a pyrpc.json config file, generates types, and starts the development server with auto-regeneration on file changes. The entry point is framework-specific: FastAPI/Flask/ASGI take a module[:app] target, Django takes the path to manage.py.

You can also pass flags to skip the wizard:

pyrpc dev --yes                          # sniff the framework, auto-detect everything
pyrpc dev --yes --framework fastapi --module main --client ../frontend

Configuration (pyrpc.json)

pyRPC stores its project configuration in a dedicated pyrpc.json file (not in pyproject.toml):

{
  "backend": {
    "framework": "fastapi",
    "entrypoint": "main:app"
  },
  "clients": [
    { "framework": "Next.js", "root": "../frontend" }
  ]
}

• backend.framework - one of fastapi, flask, django, asgi. It decides which native dev server pyrpc dev launches (uvicorn, flask run, or manage.py runserver).
• backend.entrypoint - what the dev server launches: a module[:app] target for FastAPI/Flask/ASGI, or the path to your manage.py for Django.
• backend.types_module - optional; the module whose import registers your @rpc procedures. Defaults to the module part of entrypoint. Required for Django (e.g. the views.py module that declares your procedures).
• clients[].root - one or more frontend project roots; types are written to each. Paths are resolved relative to the config file's directory.

The file is created automatically by pyrpc dev.

Manual Codegen

For CI/CD or one-off generation:

pyrpc codegen http://localhost:8000 --client ../frontend

pyrpc codegen accepts a running server URL, a saved schema file, or a Python module, and writes __pyrpc.ts to the client project root.

Quick Start Example

from pyrpc_core import rpc, model

@model
class User:
    name: str
    age: int

@rpc
def add(a: int, b: int) -> int:
    return a + b

@rpc
def greet(user: User) -> str:
    return f"Hello, {user.name}!"

Next

• Quickstart - Full server + client example
• Concepts - Mental model and protocol design