A next-generation async Python framework for building high-performance APIs, microservices, and web applications with type safety and elegance. 🚀

Documentation: https://ravyn.dev 📚

Source Code: https://github.com/dymmond/ravyn

The official supported version is always the latest released.

!!! Info "Coming from Esmerald?" If you came looking for Esmerald, you are in the right place. Esmerald was rebranded to Ravyn. All features remain and continue to grow.

Get your first Ravyn API running in minutes.

pip install ravyn[standard]

This installs Ravyn with recommended extras. You'll also need an ASGI server:

pip install uvicorn

Create a file called app.py:

from ravyn import Ravyn, get, JSONResponse

app = Ravyn()

@app.get("/")
def welcome() -> JSONResponse:
    return JSONResponse({"message": "Welcome to Ravyn!"})

@app.get("/hello/{name}")
def greet(name: str) -> JSONResponse:
    return JSONResponse({"message": f"Hello, {name}!"})

uvicorn app:app --reload

Visit http://127.0.0.1:8000/hello/World and you'll see:

{"message": "Hello, World!"}

Ravyn automatically generates interactive API documentation:

• Swagger UI: http://127.0.0.1:8000/docs/swagger
• ReDoc: http://127.0.0.1:8000/docs/redoc
• Stoplight Elements: http://127.0.0.1:8000/docs/elements

Congratulations! 🎉 You've built your first Ravyn API.

Ravyn combines the best ideas from FastAPI, Django, Flask, and NestJS into a framework designed for real-world applications. from prototypes to enterprise systems.

• ⚡ Fast: Built on Lilya and Pydantic, with async-first design
• 🎯 Type-Safe: Full Python 3.10+ type hints for better IDE support and fewer bugs
• 🧩 Flexible: Choose OOP (controllers) or functional style. or mix both
• 🔋 Batteries Included: Dependency injection, middleware, permissions, schedulers, and more
• Database Ready: Native support for Edgy ORM and Mongoz ODM
• 🧪 Testable: Built-in test client for easy testing
• 📖 Auto-Documented: OpenAPI/Swagger docs generated automatically

Ravyn uses decorators or Gateway objects to define routes.

!!! warning "Critical Requirements" 1. At least one route is required: An empty Ravyn() application does nothing. You must define routes to handle requests. 2. Return types are important: Always specify return type hints (e.g., -> dict, -> JSONResponse). Ravyn uses these to: - Serialize your data correctly - Generate accurate API documentation - Validate responses

from ravyn import Ravyn, get, post

app = Ravyn()

@app.get("/users")
def list_users() -> dict:
    return {"users": ["Alice", "Bob"]}

@app.post("/users")
def create_user(name: str) -> dict:
    return {"created": name}

from ravyn import Ravyn, Gateway, get

@get()
def list_users() -> dict:
    return {"users": ["Alice", "Bob"]}

app = Ravyn(
    routes=[
        Gateway("/users", handler=list_users)
    ]
)

!!! tip Use decorators for quick prototypes. Use Gateway + Include for scalable, organized applications.

Inject dependencies at any level. from application-wide to individual routes.

from ravyn import Ravyn, Gateway, Inject, Injects, get

def get_database():
    return {"db": "connected"}

@get()
def users(db: dict = Injects()) -> dict:
    return {"users": [], "db_status": db}

app = Ravyn(
    routes=[Gateway("/users", handler=users)],
    dependencies={"db": Inject(get_database)}
)

Learn more in the Dependencies guide.

Ravyn uses environment-based settings inspired by Django.

from ravyn import RavynSettings
from ravyn.conf.enums import EnvironmentType

class DevelopmentSettings(RavynSettings):
    app_name: str = "My App (Dev)"
    environment: str = EnvironmentType.DEVELOPMENT
    debug: bool = True

Load your settings via environment variable:

# MacOS/Linux
RAVYN_SETTINGS_MODULE='myapp.settings.DevelopmentSettings' uvicorn app:app --reload

# Windows
$env:RAVYN_SETTINGS_MODULE="myapp.settings.DevelopmentSettings"; uvicorn app:app --reload

If no RAVYN_SETTINGS_MODULE is set, Ravyn uses sensible defaults.

Learn more in Application Settings.

As your app grows, use Include to organize routes into modules.

myapp/
├── app.py
├── urls.py
└── accounts/
    ├── controllers.py
    └── urls.py

from ravyn import get, post

@get()
def list_accounts() -> dict:
    return {"accounts": []}

@post()
def create_account(name: str) -> dict:
    return {"created": name}

from ravyn import Gateway
from .controllers import list_accounts, create_account

route_patterns = [
    Gateway("/", handler=list_accounts),
    Gateway("/create", handler=create_account),
]

from ravyn import Include

route_patterns = [
    Include("/accounts", namespace="myapp.accounts.urls"),
]

from ravyn import Ravyn

app = Ravyn(routes="myapp.urls")

Now your routes are organized:

• GET /accounts/ → list_accounts
• POST /accounts/create → create_account

Learn more in Routing.

pip install ravyn[test]

Includes the RavynTestClient for testing your application.

pip install ravyn[jwt]

For JWT-based authentication.

pip install ravyn[schedulers]

For background task scheduling.

pip install ravyn[ipython]  # IPython shell
pip install ravyn[ptpython]  # ptpython shell

Learn more about the shell.

!!! warning This is for users comfortable with Python project structures. If you're new to Ravyn, continue learning the basics first.

Generate a simple project scaffold:

ravyn createproject myproject --simple

Or generate a complete scaffold (recommended for enterprise apps):

ravyn createproject myproject

This creates a ready-to-go structure with:

• Pre-configured application
• Sample routes
• Test setup

Learn more in Directives.

Now that you have Ravyn running, explore these topics:

• Dependencies - Master dependency injection
• Routing - Advanced routing patterns
• Responses - Different response types
• Testing - Test your application

• Middleware - Add request/response processing
• Permissions - Secure your endpoints
• Database Integration - Connect to databases
• Background Tasks - Run async tasks

• Settings - Environment configuration
• Deployment - Deploy your application
• OpenAPI Configuration - Customize API docs

• Python 3.10+

Ravyn is built on:

• Lilya - High-performance ASGI framework
• Pydantic - Data validation

Ravyn is the evolution of Esmerald, rebranded to align with a growing ecosystem of tools. Esmerald continues to exist for its specific use cases, while Ravyn represents the next generation with improved consistency and future-focused design.

While frameworks like FastAPI, Flask, and Django solve 99% of common problems, they sometimes leave gaps in structure and business logic organization. Ravyn was built to fill those gaps while keeping the best features from:

• FastAPI - API design and automatic documentation
• Django - Permissions and settings management
• Flask - Simplicity and flexibility
• NestJS - Controllers and dependency injection
• Starlite - Transformers and signature models

Learn more in About Ravyn.

Ravyn is an open source project and we love your contribution!

• Star us on GitHub to show your support! ⭐️
• Join our Discord to ask questions and share your projects.
• Follow us on X (Twitter) for the latest updates.

Currently there are no sponsors of Ravyn but you can financially help and support the author though GitHub sponsors and become a Special one or a Legend.

Worth mentioning who is helping us.

JetBrains