Ctrlk
官网GitHub
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Upgrade from V1 to V2

Back up V1 data, use V2.0.2 directly to complete the migration, and check items that need to be reconfigured.

Migration is one-way: V1 data can be imported into V2, but new data in V2 will not be synced back to V1. Before upgrading, keep both a complete V1 backup and the entire V1 data directory copied after fully exiting the app.

The correct path to retain your data is:V1.9.13 → V2.0.2 (complete data migration directly)You no longer need to install V2.0.0 first.

Choose according to your current situation

Current situation
Action

Still on V1 and need to keep data

Update V1 to 1.9.13, then directly install V2.0.2 following the steps on this page.

Already using V2

Upgrade to V2.0.2 normally and continue using the current V2 data; do not click [Re-migrate].

Previously failed to migrate V1 or missed some data

After creating a full backup of the current V2, you can use [Re-migrate] to start over from V1.

Do not need V1 data

You can choose [Ignore and use default values] to start with the default configuration; V1 data will not be migrated.

Confirmation before upgrading

  • V1 is not lower than 1.9.12; it is recommended to update to the final version 1.9.13 first and launch it at least once.

  • For the first migration, you can use V2.0.2 directly.

  • Custom data directories or external disks can be read and written normally.

  • Dialogs, Agents, knowledge base imports, and file processing tasks have all finished.

The migration wizard reads the current V1 data directory, not the V1 backup ZIP. The backup is for accidental recovery and cannot replace the original data directory for migration.

Steps

1

Update and back up V1

Update V1 to 1.9.13. On the data backup page, turn off [Slim Backup], create a full backup, and save the backup outside the application data directory.

2

Copy the entire V1 data directory

In V1's data settings, confirm the directory location, fully exit Cherry Studio, then copy the entire directory. Do not copy only the database files.

3

Check custom directories

When using an external hard drive, network volume, or other custom location, make sure the path is mounted and readable/writable. Do not switch to the default directory and continue migrating if the path is inaccessible.

4

First launch of V2.0.2

from V2 official download Get the V2.0.2 installer that matches your system and chip, or use the GitCode releases page or GitHub releases page. Fully exit V1, then install and launch.

5

Complete the [Data Migration Wizard]

Check the data location shown by the wizard, then select [Start Migration]. During migration, do not close the app, move the data directory, or disconnect the external disk.

6

Review the results and restart

After migration is complete, first expand the warning message, then select [Restart App].

Checks after upgrading

  • Check common model services, API keys, and the default model.

  • Check assistant groups, prompt words, Agent permissions, and knowledge base bindings.

  • Open commonly used conversations, knowledge bases, and files; only rebuild knowledge sources that fail to display.

  • In [Settings] → [Web Search], re-confirm keyword search and URL reading services.

  • Check sidebar favorites and custom CSS.

  • In [Settings] → [Data], create a new full V2 backup.

See more entry changes in [Feature Differences].

Use [Re-migrate] only if migration fails

If V1 migration previously failed or missed some data, V2.0.2 can use [Re-migrate] under [Settings] → [Data]. This operation will restart the app and rerun migration from the retained V1 data.

[Re-migrate] will permanently delete the current V2 data and will not merge V1 and V2 data. Unless V1 migration previously failed or missed some data, do not click it. Before operating, you must create a full backup of the current V2; any new V2 content that needs to be kept should also be exported separately.

When migration fails

Option
When to use
Notes

[Retry]

After fixing directory, disk, or temporary data issues

Preferred option; it will not exit the migration process.

[Save issue information]

Retry still fails and you need help

The file is saved locally only and may contain paths, content, or credentials. Provide it only to the Cherry Studio support team.

[Ignore and use default values]

Explicitly give up importing V1 data

Clear the partially written V2 data from this attempt and start from the default configuration; after that, you will no longer be prompted to migrate automatically.

[Continue using V1]

Temporarily unable to migrate and need to resume work

Reinstall V1 and continue using the original V1 data directory.

If migration fails or you mistakenly choose [Ignore and use default values], do not delete the database yourself, and do not repeatedly overwrite the installation. Keep the original V1 data and backups and contact the Cherry Studio support team.

Frequently Asked Questions

If I only have the V1 backup ZIP, can I migrate directly?

No. First restore it in a compatible V1 and confirm the data is normal, then keep the complete data directory before starting V2 migration.

Do all knowledge bases need to be reindexed?

No. Valid indexes will be migrated; only sources that show failures, are missing embedding models, or cannot be read will be handled.

References

PreviousFeature differencesNextDowngrade from V2 to V1

Last updated

Was this helpful?