Skip to content

Getting Started

This guide takes you from an empty directory to a running Zeython application with a database, a server-rendered home page and a working account system. Allow about five minutes.

Requirements

  • Python 3.11 or newer
  • pip and the standard venv module

No database server is needed to get started: new projects use SQLite. PostgreSQL and MySQL are supported through the postgres and mysql extras (see Database & Migrations).

1. Install Zeython

Create a virtual environment and install the framework, which also installs the zeython command:

python -m venv .venv
source .venv/bin/activate
pip install zeython

2. Create a project

zeython new "My Blog"
cd my_blog
pip install -e .
cp .env.example .env

zeython new generates a complete, runnable application:

my_blog/
├── app/
│   ├── Controllers/       # request handlers
│   ├── Models/            # async Active Record models
│   ├── Middleware/        # ASGI middleware
│   ├── Providers/         # your own service providers
│   ├── Jobs/              # background jobs
│   └── Console/Commands/  # custom CLI commands
├── database/
│   ├── factories/         # model factories for tests and seeding
│   └── seeders/           # seed data, run with `zeython db seed`
├── resources/
│   ├── views/             # Jinja2, Blade and Python views
│   └── css/app.css        # Tailwind source
├── routes/
│   └── web.py             # route definitions
├── migrations/            # Alembic migrations
├── tests/
├── main.py                # application entry point
├── alembic.ini
├── Dockerfile
└── .env.example

main.py is the place to start reading. It constructs the Application and registers the service providers your app uses. Every capability your application has is switched on by a line in that file.

3. Create the database

A new project includes a User model but no migration for it yet. Generate the initial migration from your models, then apply it:

zeython db revision -m "create users table"
zeython db migrate

4. Run the development server

zeython serve

Open http://127.0.0.1:8000. You will see a server-rendered welcome page, built from the Blade template resources/views/welcome.blade.html and styled with Tailwind CSS (see Views, Blade and Frontend & CSS). The server reloads automatically when you change a file.

5. Make your first authenticated request

Every new project ships with session authentication and CSRF protection enabled. Unsafe requests (POST, PUT, PATCH, DELETE) must send the CSRF token back in the X-CSRF-Token header. Any GET request issues that token as a cookie:

curl -c cookies.txt http://127.0.0.1:8000/ -o /dev/null
CSRF=$(grep csrf_token cookies.txt | awk '{print $NF}')

curl -b cookies.txt -H "X-CSRF-Token: $CSRF" -X POST http://127.0.0.1:8000/register \
  -H 'Content-Type: application/json' \
  -d '{"name": "Ada", "email": "ada@example.com", "password": "correct-horse-battery"}'

curl http://127.0.0.1:8000/users

/users is paginated (see Pagination), so the response is an envelope such as {"items": [...], "page": 1, "total": 1, ...} rather than a bare array.

Seeing a database error?

Make sure you ran both commands in step 3. The users table does not exist until the first migration is applied.

Next steps

  • Learn by building


    The Tutorial builds a real, tested, multi-model API from this same starting point.

  • Understand the design


    Architecture explains the container, service providers and router.

  • Add your own models


    Database & Migrations covers models, queries, pagination and transactions.

  • Generate code


    The CLI Reference lists every zeython make generator and command.