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
uv tool upgrade evlet
uv tool listuv 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:
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:
sudo systemctl stop evlet-acmeevlet setup --host names the service evlet-<instance>, so evlet-acme serves the instance acme.
#Check the version the project runs
.venv/bin/python -m pip show evletThe 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
.venv/bin/python -m pip install --upgrade evletTo 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:
Evlet 0.4.3 is installed but instance acme was migrated with Evlet 0.4.2; stop serving and run evlet migrate acmeSee what will change, then migrate:
evlet migrate acme --plan
evlet migrate acmeevlet 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:
Instance acme: installed notes
Applied migrations: none; schema is current
Framework migrations: 0009_admin_username, 0010_split_files
Backup: .../instances/acme/data/backups/20261113T071235113355Z.sqlite3Repeat for every instance in the project.
#Start again
sudo systemctl start evlet-acmeOr 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:
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 migrateagain. 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 restorewith the backup thatevlet migrateprinted. 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: runevlet migrateagain to bring it forward, or put the old Evlet back in the project. Seeevlet 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.