Installation

Meet Almasix

Almasix is a Python web framework with expressive structure and first-class async/await for ASGI. Create applications with almasix new, then drive them with Smith — Almasix’s in-app CLI:

almasix new blog
cd blog
pip install -e .
smith serve

Templates, routing, validation, localization, and the ORM all live behind the almasix.* package. You write application code; Almasix boots the container, compiles your routes, and serves them over ASGI.

Note

Almasix is inspired by Laravel’s application shape. The public APIs, CLI, ORM, and view engine are Almasix’s own — Smith, Articulate, and Prism.

Requirements

• Python 3.11 or higher
• pip and a virtual environment
• Node.js 18+ (optional but recommended) for the default Vite + Tailwind toolchain

Creating an Almasix project

1. Install Almasix (from PyPI, or from a local checkout while developing against main):

   pip install almasix
   # or, from a local clone of the framework:
   pip install -e /path/to/almasix

2. Create a new application:

   almasix new blog
   cd blog

3. Create a virtual environment and install dependencies:

   python -m venv .venv
   source .venv/bin/activate
   pip install -e .                 # your app
   pip install almasix               # or -e /path/to/almasix during local development

4. Install frontend dependencies (Vite + Tailwind):

   npm install

5. Start the development server:

   smith serve

   Visit the URL Smith prints (typically http://127.0.0.1:3000). In another terminal, run npm run dev while iterating on CSS/JS.

Smith

smith belongs to your application, not to Almasix itself. Step 3 installs it into the project’s virtualenv, so with that environment active you can run smith serve, smith migrate, smith loupe, and so on. The root smith file works as python smith … without any install step.

Installing the framework globally — with pipx install almasix, say — gives you the almasix command only, so one application’s CLI never leaks onto your PATH system-wide.

Directory structure at a glance

A fresh application looks like this:

blog/
  app/
    http/controllers/
    models/
    providers/
  bootstrap/app.py
  config/
  database/migrations/
  database/seeders/
  resources/css/
  resources/js/
  routes/web.py
  routes/api.py
  package.json
  vite.config.js
  smith

Read more in Directory Structure and Asset Bundling.

Database drivers

SQLite works out of the box. For other engines, install the matching optional extra:

pip install almasix[pgsql]    # PostgreSQL
pip install almasix[mysql]    # MySQL / MariaDB
pip install almasix[sqlsrv]   # SQL Server
pip install almasix[oracle]   # Oracle (optional)
pip install almasix[db]       # all of the above

Configure connections in config/database.py — see Database: Getting Started.

Next steps

• Directory Structure
• Middleware
• Articulate
• Smith Console