Docs

Upgrade Evlet

Upgrading has two parts. First you upgrade the evlet command. Then you upgrade each project, because each project keeps its own copy of Evlet, and migrate each of its instances.

#Why two parts

evlet setup gives every project its own Python environment, .venv, with its own Evlet. Inside a project, every evlet command runs with that copy, and so does the project's service on a server.

So uv tool upgrade evlet changes the command you use to create new projects. It does not change any project you already have. A project moves to a new version only when you upgrade its .venv. Evlet has no single command that does this for you yet, so the steps below do it by hand.

#1. Upgrade the evlet command

Terminal
uv tool upgrade evlet
uv tool list

uv tool list shows the new version, for example evlet v0.4.3.

If uv says Nothing to upgrade and names a pinned version, you installed Evlet with ==, such as uv tool install evlet==0.4.2. uv keeps that pin. Install again without it:

Terminal
uv tool install evlet@latest

#2. Upgrade each project

Do this for each project, one at a time. The commands run from inside the project folder.

#Stop the instances

Stop everything that serves the project's instances: evlet dev or evlet serve in a terminal (Control-C), and the service on a server:

Terminal
sudo systemctl stop evlet-acme

evlet setup --host names the service evlet-<instance>, so evlet-acme serves the instance acme.

#Check the version the project runs

Terminal
.venv/bin/python -m pip show evlet

The Version: line is the project's Evlet. On Windows, use .venv\Scripts\python.exe in place of .venv/bin/python here and below.

#Upgrade the project's Evlet

Terminal
.venv/bin/python -m pip install --upgrade evlet

To move to one exact version, name it: .venv/bin/python -m pip install evlet==0.4.3. Your apps say which Evlet versions they accept in their pyproject.toml, for example evlet>=0.4.0,<0.5. Check that each app accepts the new version before you upgrade.

#Migrate each instance

A new Evlet version can bring its own changes to the database. Until you migrate, the instance refuses to start, and says so:

Output
Evlet 0.4.3 is installed but instance acme was migrated with Evlet 0.4.2; stop serving and run evlet migrate acme

See what will change, then migrate:

Terminal
evlet migrate acme --plan
evlet migrate acme

evlet migrate makes a backup first, then applies your apps' migrations and Evlet's own, all in one go. If any step fails, the instance is left as it was. The output lists what it applied and where the backup is:

Output
Instance acme: installed notes
Applied migrations: none; schema is current
Framework migrations: 0009_admin_username, 0010_split_files
Backup: .../instances/acme/data/backups/20261113T071235113355Z.sqlite3

Repeat for every instance in the project.

#Start again

Terminal
sudo systemctl start evlet-acme

Or run evlet serve acme or evlet dev --instance acme again. Sign in and check the site.

#All the steps together

On a server, for a project with one instance called acme:

Terminal
uv tool upgrade evlet
cd /path/to/myproject
sudo systemctl stop evlet-acme
.venv/bin/python -m pip install --upgrade evlet
evlet migrate acme --plan
evlet migrate acme
sudo systemctl start evlet-acme

#If something goes wrong

  • The migration failed. Nothing was changed. Read the message, fix the cause and run evlet migrate again. To go back instead, install the old version in the project, such as .venv/bin/python -m pip install evlet==0.4.2, and start the instance.
  • You need the old data back. Stop the instance and run evlet restore with the backup that evlet migrate printed. Restore puts back the whole set of database files, and keeps the files it replaces. A backup made by an older Evlet will not start on the new one: run evlet migrate again to bring it forward, or put the old Evlet back in the project. See evlet restore.

#From 0.4.2 to 0.4.3

Evlet 0.4.3 brings two changes to every instance. evlet migrate applies both, after one backup.

The Administrator's username is now admin. It was administrator in 0.4.2. The step 0009_admin_username renames the account and keeps its password, email and two-step sign-in. Sign in as admin afterwards. If the instance already has an active admin called admin, that account becomes the Administrator and keeps its own password, and the old administrator account becomes an ordinary admin. An account called admin that is not an active admin stops the step: rename it first.

Each instance's database is now four files. The step 0010_split_files moves sign-in sessions, the tool-call log and Eva out of database.sqlite3 into sessions.sqlite3, logs.sqlite3 and eva.sqlite3 beside it. A long background job no longer makes pages fail with "database is locked". People stay signed in. Back up and restore the four files together, with the new evlet backup and evlet restore commands.

Your apps keep their evlet>=0.4.0,<0.5 dependency. Scripts and tests that sign in as administrator should use admin.