Hello, world.
Your first backend.

Learn to build Python backends, starting with one working endpoint.

Experimental · Python 3.13+

Karak is a Python framework for building async HTTP applications. Define endpoints with Python functions, validate inputs with type annotations, and share services through typed resource contexts.

Start with a small application that returns a greeting. You can add the capabilities your backend needs as you go. Karak is experimental and currently suited to local development and evaluation.

Install

You will need Python 3.13+ and uv. Open a terminal and run:

git clone https://github.com/grandimam/karak.git
cd karak
uv sync

Stay in the karak directory for the steps below. See installation if you need more help with setup.

Create an application

Create a file called main.py in that directory:

from karak import Karak
from karak import Router

router = Router()


@router.get("/")
async def index():
    return "Hello from Karak"


app = Karak(router=router)

This tells Karak to run index() when someone visits /. The text you return becomes the response. Use async def for your endpoints in the current version.

Run it

uv run uvicorn main:app --reload

Open localhost:8000 in your browser. You should see:

Hello from Karak

Change the returned text, save main.py, and refresh the browser. The --reload option restarts the development server when you edit a file. Press Ctrl+C in the terminal when you want to stop it.

Add to your application

Add another endpoint to give the application a second URL, then accept path and query values to make its response depend on caller input. For the request's headers, cookies, and body, use request context.

As the application grows, start with the recommended project layout, split routes into modules, and share services across handlers. Each guide includes examples you can run independently; complete main.py examples replace the previous file, while smaller snippets explain where to add them.