Skip to content

Installation

This page covers how to create a new Nori project. If you want a hands-on walkthrough of building a feature, head to the Tutorial after installing.

Prerequisites

  • Operating system: Linux or macOS. Windows users should use WSL2 — Nori runs cleanly inside it. Native Windows is not currently tested or supported (Gunicorn, the production server, doesn't run on Windows).
  • Python 3.10+ — check with python3 --version
  • git — required for the installer's git init step
  • (production only) MySQL 8+ or PostgreSQL 14+ — SQLite is fine for development
curl -fsSL https://nori.sembei.mx/install.py | python3 - my-project

What this does, in order:

  1. Pulls the latest release zip from GitHub
  2. Copies only the files that belong in a fresh project — no CHANGELOG.md, no docs/, no .github/, no framework tests/, no mkdocs.yml
  3. Writes a project-scoped README.md
  4. Copies .env.example to rootsystem/application/.env
  5. Initializes a fresh git repo — your first commit is yours, not Nori's history
  6. Creates .venv and installs dependencies

When it finishes:

cd my-project
source .venv/bin/activate
python3 nori.py migrate:init
python3 nori.py serve

Fresh projects default to SQLite (db.sqlite3 at the project root) — no database server needed for first run. To use MySQL or PostgreSQL, edit rootsystem/application/.env before running migrate:init. See Deployment for production database setup.

Flags

Flag What it does When to use it
--no-venv Skip creating .venv (implies --no-install) You manage envs differently (Poetry, asdf, conda, container-only)
--no-install Create .venv but skip pip install Air-gapped envs, or you want to inspect requirements.txt first
--version V Pin a specific release (e.g. --version 1.10.0) Reproducible installs in CI or team handoffs — defaults to latest

Pinning a version is especially useful for CI:

curl -fsSL https://nori.sembei.mx/install.py | python3 - my-project --version 1.10.0

What gets created

my-project/
├── nori.py                       # CLI bootstrap
├── requirements.txt              # User-owned dependencies
├── requirements.nori.txt         # Framework-pinned deps (replaced on framework:update)
├── requirements-dev.txt          # Dev/test dependencies
├── Dockerfile
├── docker-compose.yml
├── gunicorn.conf.py              # Production server config
├── pytest.ini
├── .env.example
├── .gitignore
├── .dockerignore
├── LICENSE
├── README.md                     # Project-scoped, generated by installer
├── rootsystem/
│   ├── application/
│   │   ├── core/                 # Framework code (replaced on framework:update)
│   │   ├── models/               # Your models
│   │   ├── modules/              # Your controllers
│   │   ├── routes.py
│   │   ├── settings.py
│   │   └── .env                  # Copied from .env.example
│   ├── static/
│   └── templates/
├── tests/                        # Empty, ready for your tests
└── .venv/                        # Created unless --no-venv was passed

The exact set of paths lives in .starter-manifest.json at the repo root, read by the installer from each release zip.

Verifying the install

cd my-project
source .venv/bin/activate
python3 nori.py serve

You should see:

INFO:     Uvicorn running on http://0.0.0.0:8000

Open http://localhost:8000 — you should see the welcome page. Stop with Ctrl+C.

Manual install (contributors or restricted environments)

If your environment blocks curl | python3 (corporate proxies, security policies) or you're contributing to Nori itself:

git clone https://github.com/sembeimx/nori.git my-project
cd my-project
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example rootsystem/application/.env
python3 nori.py migrate:init
python3 nori.py serve

This brings the framework's dev artifacts (CHANGELOG.md, docs/, mkdocs.yml, etc.). If you're using this path because of policy, those files don't affect your application — you can leave them or delete what you don't need. If you're a framework contributor, you want them.

Troubleshooting

Python 3.10+ required

The installer needs Python 3.10 or newer. Check with python3 --version. On macOS: brew install python. On Linux: install from your distro repos or use pyenv.

No releases found or Could not reach GitHub

The installer hits the GitHub API to find the latest release. If you're behind a corporate proxy or hitting unauthenticated rate limits, set a token:

export GITHUB_TOKEN=ghp_xxxx
curl -fsSL https://nori.sembei.mx/install.py | python3 - my-project

Directory 'my-project' already exists

Pick a different name or remove the existing directory first. The installer refuses to overwrite — that's deliberate, to protect work in progress.

Updating an existing project

To bring an existing project up to a newer Nori release:

python3 nori.py framework:update

This replaces the framework code (rootsystem/application/core/, requirements.nori.txt) without touching your application code. See the CLI Reference for details and flags.

Next steps