Skip to content

Upgrading Whittl

Whittl is format-stable across versions. Your projects, settings, skills, and templates carry forward unchanged. This page covers exactly what to expect and the few edge cases that need attention.

The happy path

  1. New version arrives (Help → Check for Updates in v2.4+, or browser download in v2.3 and earlier)
  2. Old version is uninstalled, new version installs over it
  3. Launch new Whittl
  4. Everything is where you left it

No data migration step. No manual import. Projects at ~/.whittl/projects/ are read by every Whittl version.

In-app updates (v2.4 and later)

Help → Check for Updates:

  1. Dialog shows "Whittl v2.X.X is available" with a Download button
  2. Click Download — progress bar appears, downloads happen in-app
  3. SHA256 verifies on completion
  4. "Restart to install" button appears
  5. Click it — Whittl closes, installer runs silently over existing install, new Whittl launches automatically

No browser, no Downloads folder hunt, no UAC prompt (per-user install).

If you quit Whittl between download and install, the downloaded installer persists. Next launch offers "Install v2.X.X now" without re-downloading.

Upgrading to v2.6.1

From v2.6.0, Help > Check for Updates does it. Nothing needs migrating. Two things to know:

  • The first time the AI works on a project that has tests, Whittl installs pytest into its own Python so the test gate can run them, and the status bar says so. It needs an internet connection that once.
  • An answer the AI gave in the chat now reaches its next turn. If it lists ideas and you reply "do all of them", it works from that list.

Upgrading to v2.6.0

From v2.5.0, on Windows or Linux, Help → Check for Updates does the whole upgrade. Nothing needs migrating. Three things look different afterwards:

  • Plugins are new. The ones that ship as part of Whittl (the Assets, Archives, Terminal and Help tabs, and the context gauge in the status bar) are on from the start. Any plugin you add stays off until you switch it on in Edit > Plugins. See Plugins.
  • The Expand checkbox is gone. Your message is sent exactly as you typed it.
  • Ollama asks for a 16,384-token context window by default (it was 8,192). A value you chose yourself in Preferences > Ollama is kept.

On v2.4.1 for Windows, see the next section first.

v2.4.1 on Windows: "Could not check for updates"

If you are on v2.4.1 on Windows and Help → Check for Updates reports that it could not check for updates, that is not your internet connection. In September 2026 the download server moved to a newer certificate chain. The v2.4.1 updater verifies connections with Windows' own certificate store, and on some machines that store cannot verify the new chain, so the check fails before it ever reaches the server. Nothing in v2.4.1 can be changed at this point.

What to do: download the current installer from the link in your purchase email and run it over your existing install. Projects, settings, skills and API keys carry forward unchanged. From v2.5.0 on, Whittl verifies its own connections with a bundled certificate authority list, so in-app updates work again.

Linux is not affected. The AppImage's updater has always carried its own certificate bundle.

Browser updates (v2.3 and earlier)

The pre-v2.4 flow:

  1. Check for Updates → opens your browser to the R2 download URL
  2. Download the installer manually
  3. Close Whittl
  4. Run the installer (click through SmartScreen "Run anyway")
  5. Relaunch Whittl

Users upgrading from v2.3 to v2.4 go through this flow one last time. Every upgrade after is in-app.

What auto-migrates

  • Projects — no change, same format
  • API keys — encrypted same way, forward-compatible
  • Settings — new settings default to sensible values, old settings preserved
  • Skills — read the same regardless of version
  • Templates — forward-compatible
  • Archives — not touched
  • Favorites — OpenRouter favorites preserved

Historically, one migration was needed (v2.0 → v2.1 OpenRouter model naming). It ran automatically on first launch of v2.1; nothing for users to do.

What doesn't carry across

  • Recent file list — rebuilt as you open files in the new version
  • Window position / size — resets on first launch of a major version
  • Cached model lists — OpenRouter refreshes on first use

Nothing user-meaningful.

Downgrading

Going BACK to an older version:

  1. Uninstall current version (Control Panel → Programs)
  2. Download the older version from https://pub-573d835c3fa144b4943659b8717d7fd1.r2.dev/Whittl/2.X.X/: Whittl-2.X.X-windows-setup.exe on Windows, Whittl.AppImage on Linux
  3. Install

Caveat: if you opened a project in a NEWER Whittl that wrote new metadata fields, the OLDER Whittl might not read them cleanly. Generally Whittl is forward-compatible both ways, but forward-then-backward is the riskiest case. Keep backups via ~/.whittl/projects/ copies if you plan to downgrade.

If an upgrade breaks something

  1. Check the release notes for the new version for behavior changes
  2. Check Common Issues — version-transition bugs show up there first
  3. Reinstall the previous version (see Downgrading above)
  4. Report the bug with the error message + OS + both Whittl versions (old and new)

Rare but possible. Upgrade paths are tested on a fresh VM before each release, but your workflow might exercise edge cases the test suite doesn't.

Backup checklist before a major upgrade

Paranoid upgraders can make this pre-upgrade routine:

  1. Copy ~/.whittl/ to ~/.whittl.backup-v2.X/
  2. Upgrade
  3. Verify a project opens and Test Run works
  4. Delete the backup when you're confident

~/.whittl/ is usually under 100 MB — the copy takes seconds.

What's next

  • Privacy — what the update check sends (nothing beyond the version query)
  • Folder Structure — what's under ~/.whittl/ and whether it survives upgrades