Skip to content

Migration

Jump to bottom
Mario Limonciello edited this page Sep 1, 2026 · 11 revisions

Migration

v9.2.0 - v9.3.0

Linux

Lemonade 9.2.0 and earlier did not include a service to run lemonade-server automatically.

  • Users had to start up the lemonade-server process manually.
  • This implies that the models and engine are stored in the home directory of the user that launched lemonade-server.

Versions of lemonade after 9.2.0 include a systemd service that will run lemonade-server under a confined environment with a dedicated user.

  • systemd will manage the life cycle of the process and restart it.
  • The process can not access engines or models in the home directory of your previous user.

Migration

  • Check where lemonade created the new folders. Take WorkingDirectory path from cat /etc/systemd/system/lemonade-server.service. So it should be probably /var/lib/lemonade/or/opt/var/lib/lemonade/. Replace YOUR_WORKING_DIRECTORY` with this path.
  • Manually move the engines from ~/.cache/lemonade to YOUR_WORKING_DIRECTORY/.cache/lemonade. sudo mv ~/.cache/lemonade YOUR_WORKING_DIRECTORY/.cache
  • Manually move the models from ~/.cache/huggingface to YOUR_WORKING_DIRECTORY/.cache/huggingface. sudo mv ~/.cache/huggingface YOUR_WORKING_DIRECTORY/.cache
  • Lemonade created new lemonade user and group, our moved folders need this as new ownership sudo chown -R lemonade:lemonade YOUR_WORKING_DIRECTORY

Disabling service

If you would prefer not to use the systemd service you can disable the service with systemctl disable lemonade-server.service

Modifying the service

If you want to disable confinement rules, change the process or any other settings you can modify the service with systemctl edit lemonade-server.service and then restart it with systemctl restart lemonade-server.service

v9.3.0 - v9.3.1

Windows

Lemonade v9.3.1 completely overhauls the support for Ryzen AI SW as we move from RAI 1.6 to 1.7.

Breaking Changes

  • All oga-* recipes have been replaced by a monolithic ryzenai-llm recipe (npu vs. hybrid vs. cpu is auto-detected).
  • All previous oga-hybrid and oga-npu models are invalidated and no longer supported.
  • The oga-cpu models are still there, the recipe is just changed to ryzenai-llm.

Migration

Prior to updating to Lemonade v9.3.1, we suggest removing all RAI 1.6 models. The simplest way to do this is to open the Lemonade App and click the "trash can" delete button next to all downloaded oga-hybrid and oga-npu models. You can also use lemonade-server list to see your installed models on the command line and lemonade-server delete MODEL to remove a model.

If you've already upgraded to v9.3.1, you can go into your Hugging Face cache directory (which defaults to ~/.cache/huggingface/hub, where ~ is your home directory). Delete any model folder whose name starts with models--amd. You may also want to open your user models file (at ~/.cache/lemonade/user_models.json) and remove any entry that has an oga-* recipe.

New Models

Lemonade v9.3.1 provides access to all RAI 1.7 NPU and Hybrid models, about 70 total. For support with these models, please file an issue on the Ryzen AI SW repo.

v9.3.x - v9.4.0

Linux

There is now only a single .deb file in each release, lemonade-server.deb. This installer includes Lemonade Server as well as the web app.

The electron app is now available as a standalone AppImage. The benefits of this are:

  1. The AppImage can be added at any time to a lemonade-server.deb install.
  2. The AppImage can be installed on a client device, for use with a remote Lemonade Server, without any need to also install Lemonade Server on that client.

.deb users migrating to Lemonade v9.4.0 need to first sudo apt remove lemonade or sudo apt remove lemonade-server-minimal, depending on which .deb they had installed previously.

v10.x - v10.1

This is the spring cleaning update. The purpose of this work is to reset some of the early design choices that have been limiting the reach and flexibility of Lemonade.

  1. The default port is changing from 8000 to 13305.
  2. The lemonade-router executable has been renamed to lemond.
  3. The lemonade-server CLI is deprecated. The installers on all operating systems will start the lemond service automatically after install and on startup, so no more need for lemonade-server serve.
  4. A new lemonade CLI is available to manage lemond, including a longstanding feature request: lemonade config lets you view the entire configuration at once, and change the port, host, max loaded models, llamacpp backend, etc. etc. at runtime without restarting the service.
  5. The lemonade config command replaces the lemonade-server serve CLI args and the env vars / conf file for configuring lemond.
    • The only remaining lemond CLI args are --port and --host, for in case you need to change those to start lemond in the first place.
    • The only remaining env vars are:
      • LEMONADE_API_KEY and HF_TOKEN, since those are secrets.
      • HF_HOME and HF_HUB_CACHE are also still respected.

Please see the Configuration Guide for full instructions on the new lemonade config command.

Note: The deprecated lemonade-server CLI will be available for 1 month, and will be removed in the first release that comes after May 6, 2026.

Additional Notes:

  • Clear any API keys and manually migrate them using sudo systemctl edit lemonade-server.
  • If you had a custom models location set by HF_HOME or HF_HUB_CACHE and your models aren't showing up, do sudo systemctl edit lemonade-server and add HF_HOME or HF_HUB_CACHE there.
  • Logs now stream over websocket on port 9000 by default.

v11.7.x / v11.8.0 - v11.8.1

Linux (.deb / PPA systemd service)

v11.8.0 moved the service's files to follow the Filesystem Hierarchy Standard, but shipped a migration bug that could hide your config.json and downloaded models after an apt upgrade (see #3387). v11.8.1 fixes the migration and keeps models under the service's state directory so they are never copied across drives.

Where the systemd service keeps things:

v11.7.x and earlier v11.8.0 v11.8.1
Config (config.json, …) /var/lib/lemonade/.cache/lemonade/ /var/lib/lemonade/ /var/lib/lemonade/
Downloaded backends /var/lib/lemonade/.cache/lemonade/bin/ /var/cache/lemonade/bin/ /var/cache/lemonade/bin/
Models (Hugging Face) /var/lib/lemonade/.cache/huggingface/ /var/cache/huggingface/ /var/lib/lemonade/.cache/huggingface/

(macOS and embedded installs are unaffected)

If you upgraded from v11.7.x (or earlier) straight to v11.8.1 — nothing to do. v11.8.1 automatically moves your config.json and backends into place and finds your models where they already are.

If you ran v11.8.0, did nothing to work around the bug, then upgraded to v11.8.1 — nothing to do. Your data never actually moved under v11.8.0, so v11.8.1 recovers it the same way as above. (If v11.8.0 wrote out a fresh default config.json, v11.8.1 will not overwrite it; your previous settings are preserved at /var/lib/lemonade/.cache/lemonade/config.json, and you can re-apply them with lemonade config set.)

If you installed v11.8.0 fresh, or manually moved your data into the v11.8.0 layout, then upgraded to v11.8.1 — your config and backends carry over automatically, but any models you downloaded while on v11.8.0 live in /var/cache/huggingface, whereas v11.8.1 resolves models under /var/lib/lemonade/.cache/huggingface. Rather than moving the data, point the service back at the v11.8.0 location by restoring the HF_HOME setting the release dropped:

sudo systemctl edit lemond

Add these lines in the editor, then save and exit:

[Service]
Environment=HF_HOME=/var/cache/huggingface

Then restart the service and confirm your models are found:

sudo systemctl restart lemond
lemonade list

If you were on v11.7.x, upgraded to v11.8.0 (which stopped showing your models), downloaded more models while on v11.8.0, then upgraded to v11.8.1 — your models are now split across two locations: the originals in /var/lib/lemonade/.cache/huggingface (which v11.8.1 uses) and the ones you added under v11.8.0 in /var/cache/huggingface. Because they are in two places, the HF_HOME override above can only point at one of them, so consolidate them into the v11.8.1 location instead:

sudo systemctl stop lemond
sudo mkdir -p /var/lib/lemonade/.cache/huggingface/hub
sudo cp -a /var/cache/huggingface/hub/. /var/lib/lemonade/.cache/huggingface/hub/
sudo rm -rf /var/cache/huggingface
sudo chown -R lemonade:lemonade /var/lib/lemonade/.cache/huggingface
sudo systemctl start lemond
lemonade list

Windows

v11.8.0 changed the configuration directory location on Windows. This change was not documented in the original PR #3028, which incorrectly stated that Windows paths were "unchanged" and that the old location was %LOCALAPPDATA%.

Where Windows keeps configuration:

v11.7.x and earlier v11.8.0+
Config (config.json, …) %USERPROFILE%\.cache\lemonade\ %USERPROFILE%\.config\lemonade\
Models (Hugging Face) %USERPROFILE%\.cache\huggingface\ %USERPROFILE%\.cache\huggingface\

If you upgraded from v11.7.x to v11.8.0 or later — v11.8.0+ automatically migrates configuration files (config.json, user_models.json, recipe_options.json, mcp_servers.json, jobs.json) from %USERPROFILE%\.cache\lemonade\ to %USERPROFILE%\.config\lemonade\ on first startup. Models are unaffected and remain in %USERPROFILE%\.cache\huggingface\.

No manual action is needed. If you want to use the old cache directory for both cache and config (portable install behavior), pass the cache directory as the first argument: lemond %USERPROFILE%\.cache\lemonade

Docker

The container path /opt/lemonade/.config/lemonade must be persisted by adding a volume before upgrading to 11.8.0. If you already upgraded o it, you must copy the live data from within the container to an existing volumes before recreating the container in order to save config files then restore them afterward.

See https://github.com/lemonade-sdk/lemonade/blob/v11.8.0/docs/guide/install/docker.md#docker-compose-setup

Clone this wiki locally