> For the complete documentation index, see [llms.txt](https://docs.cherryai.com.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherryai.com.cn/docs/en-us/cherry-studio/installation/v1-to-v2-migration.md).
# Upgrade from V1 to V2
{% hint style="danger" %}
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.
{% endhint %}
{% hint style="warning" %}
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.
{% endhint %}
## 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.
{% hint style="warning" %}
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.
{% endhint %}
## Steps
{% stepper %}
{% step %}
### 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.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### First launch of V2.0.2
from [V2 official download](https://cherryai.com.cn/download) Get the V2.0.2 installer that matches your system and chip, or use the [GitCode releases page](https://gitcode.com/CherryHQ/cherry-studio/releases/v2.0.2) or [GitHub releases page](https://github.com/CherryHQ/cherry-studio/releases/tag/v2.0.2). Fully exit V1, then install and launch.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### Review the results and restart
After migration is complete, first expand the warning message, then select \[Restart App].
{% endstep %}
{% endstepper %}
## 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\]](/docs/en-us/cherry-studio/installation/v1-v2-feature-differences.md).
## 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.
{% hint style="danger" %}
\[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.
{% endhint %}
## 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. |
{% hint style="danger" %}
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.
{% endhint %}
## 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
* [Cherry Studio V2 official download](https://cherryai.com.cn/download)
* [Cherry Studio V1 official download](https://cherryai.com.cn/download/v1)
* V2.0.2 release page:[GitCode](https://gitcode.com/CherryHQ/cherry-studio/releases/v2.0.2) · [GitHub](https://github.com/CherryHQ/cherry-studio/releases/tag/v2.0.2)
* [Official migration design notes](https://github.com/CherryHQ/cherry-studio/blob/main/src/main/data/migration/v2/README.md#version-compatibility-gate)
* [Issue reports and feature suggestions](/docs/en-us/question-contact/suggestions.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.cherryai.com.cn/docs/en-us/cherry-studio/installation/v1-to-v2-migration.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.