// OPENBOX DOCS
Upgrading to OpenBox 3.0
Schema 6 and 1-5 migration, plugin API v2, Python 3.11, and the removed surfaces.
OpenBox 3.0 keeps library schema 7, backup format 2, sync format 3, and /api/v2. A 2.0 or 2.1 library opens without migration. The breaks run the other way: 3.0 will not boot a schema 6 file, will not run a v1 plugin, will not roll a library back, and will not start on Python 3.10.
Before you upgrade
- Schema 6 library (a 1.19 library that 2.1 has not opened): quit OpenBox, then either run
openbox --migrate-libraryon 3.0 or open the library once on 2.1 before installing 3.0. Startup does not upgrade it. The command keepslibrary.v6.backup.json. - Schema 1-5 library: open it on OpenBox 2.1 before installing 3.0. 3.0 migrates schema 6 only.
- Plugin without
"api_version": 2: add it. 3.0 refuses a missing version or1withPLUGIN_API_RETIRED. - Source run on Python 3.10: install Python 3.11 or newer. The Rust server itself needs no Python.
- Need
openbox --rollback-library: it is gone. OpenBox 2.1.0 is the last build that restoreslibrary.v6.backup.json.
Upgrade steps
- Quit OpenBox.
- Migrate a schema 6 library with
openbox --migrate-library; a schema 7 library needs no migration. - Install 3.0 over 2.1, or over an older build after the library is schema 7.
- Start OpenBox.
GET /api/v2/versionreportsversion3.0.0,api_version2,state_schema7,plugin_api_version2,backup_format2,sync_format3, andruntime: "rust".
What changed
- The backend is the Rust
openbox-serverwith zero bundled CPython. The Python fallback (OPENBOX_BACKEND=python) still needs Python 3.11+. - Plugin API v1 and
plugin_runner.pyare gone. openbox --rollback-libraryexits 4 and changes no file.- Python 3.10 is no longer supported.
- The public API remains
/api/v2; unversioned/api/*and/api/v1/*stay retired.
What did not change
- Library schema 7, the required envelope, and backup format 2 (format 1 is still read).
- Sync format 3.
/api/v2and/api/host.- The SQLite read model: still a projection; deleting
sqlite_readmodel.dbloses nothing. - The AppImage glibc floor (
GLIBC_2.35on Ubuntu 22.04).
If something goes wrong
STATE_SCHEMA_TOO_OLD: runopenbox --migrate-library; for schema 1-5, open the library on 2.1 first.PLUGIN_API_RETIRED: set"api_version": 2inplugin.json.ROLLBACK_REMOVED: install OpenBox 2.1.0 if you needlibrary.v6.backup.json.- The app will not start on Python 3.10: install 3.11+ for the fallback, or use a packaged 3.0 build (no Python required).