Warning for Breaking Changes
Data migration, version paths, and rollback limitations you must understand before upgrading to V2.
V2 is not a simple overwrite update. It changes the data structure and also adjusts the entry points and behavior of features such as Assistant, Agents, Knowledge Base, web search, and files.
Data from V1 can only be migrated one way to V2. New sessions, Agents, settings, and files in V2 will not be synchronized back to V1, and backups between V1 and V2 cannot be restored to each other.
V2.0.2 can directly migrate V1
When you need to keep V1 data, follow V1.9.13 → V2.0.2 (complete data migration directly) the procedure, and you no longer need V2.0.0 as an intermediary.
Still on V1 and need to keep data
Update V1 to 1.9.13, make a full backup, then install V2.0.2 directly.
Already using V2
Upgrade to V2.0.2 normally and continue using the current V2 data.
Previously failed to migrate V1 or missed some data
First make a full backup of the current V2, then consider using [Re-migrate].
Do not need V1 data
You can choose [Ignore and use default values], but V1 data will not be migrated.
A normal upgrade to V2.0.2 does not require clicking [Re-migrate]. This operation will permanently delete the current V2 data and then re-import from the original V1 data; unless the previous V1 migration failed or data was missed, do not click it.
Must be completed before upgrading
Update V1 to 1.9.13 and start it normally at least once.
Turn off [Lightweight Backup] and create a full V1 backup.
Fully quit Cherry Studio, then copy the entire V1 data directory.
When using a custom directory or external drive, confirm that the path is mounted and readable/writable.
The migration wizard reads the current V1 data directory, not the backup ZIP. The backup is for unexpected recovery and cannot replace the original data directory for migration.
[Re-migrate] is not data merging
V2.0.2 adds [Re-migrate] under [Settings] -> [Data]. It is only used to fix cases where the previous V1 migration failed or data was missed.
Before proceeding, you will be asked to confirm the following:
The current V2 data will be permanently deleted and cannot be undone.
The original V1 data will be kept and re-imported after restart.
You must first create a full backup of the current V2.
A full backup will not automatically merge V1 and V2 data. If there is new V2 content you want to keep, please export it separately or keep a full backup first.
The [v1 legacy data] option under [Settings] -> [Data] -> [Clear Cache] will delete the original V1 data required for [Re-migrate]. Do not clear this item before confirming the migration result is complete and keeping an independent backup.
Key checks after upgrading
Model services, API Key, and default model; Anthropic OAuth will not be migrated and must be replaced with an API Key.
Assistant groups, prompt order, Agent tool permissions, and Knowledge Base bindings.
Knowledge base failure sources, keyword search for web search, and URL retrieval services.
Custom CSS, sidebar favorites, and missing files.
See the complete comparison at [Feature Differences].
Migration failed or rollback is needed
Prefer [Retry], and continue after fixing data directory, disk, or data issues.
[Save problem information] only saves locally; the file may contain paths, content, or credentials. Provide it only to the Cherry Studio support team.
[Ignore and use default values] will start from the default configuration, and V1 data will not be migrated.
Returning to V1 normally does not require deleting the database, and do not restore a V2 backup to V1.
Do not delete or replace the database yourself. If you make a mistake, cannot confirm the data directory, or need to re-migrate, first keep all backups and data directories, then contact the Cherry Studio support team.
Continue reading
Download entry
Last updated
Was this helpful?