> 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/v2-breaking-update-notice.md).

# Warning for Breaking Changes

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.

{% hint style="danger" %}
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.
{% endhint %}

## 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.

| Current situation                                   | What to do                                                                         |
| --------------------------------------------------- | ---------------------------------------------------------------------------------- |
| 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. |

{% hint style="danger" %}
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.
{% endhint %}

## Must be completed before upgrading

1. Update V1 to 1.9.13 and start it normally at least once.
2. Turn off \[Lightweight Backup] and create a full V1 backup.
3. Fully quit Cherry Studio, then copy the entire V1 data directory.
4. 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.

{% hint style="danger" %}
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.
{% endhint %}

## 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\]](/docs/en-us/cherry-studio/installation/v1-v2-feature-differences.md).

## 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.

{% hint style="danger" %}
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.
{% endhint %}

## Continue reading

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Feature differences</strong></td><td>View what is automatically migrated, what needs review, and what will not be inherited.</td><td><a href="/pages/c312737045c9309d7842e93b2a53ccd64d817327">/pages/c312737045c9309d7842e93b2a53ccd64d817327</a></td></tr><tr><td><strong>Upgrade V1 to V2</strong></td><td>Complete backup, migration, and verification in the correct version order.</td><td><a href="/pages/b96124efb8e488991e8127d8e06213db0d7766ac">/pages/b96124efb8e488991e8127d8e06213db0d7766ac</a></td></tr><tr><td><strong>Downgrade V2 to V1</strong></td><td>Learn the precautions for rollback, backups, and database handling.</td><td><a href="/pages/b59908f9453516aaf15d24cdc466d05eef81b78d">/pages/b59908f9453516aaf15d24cdc466d05eef81b78d</a></td></tr></tbody></table>

## Download entry

* [Official V1 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)
* [V2 official download](https://cherryai.com.cn/download)


---

# 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/v2-breaking-update-notice.md?ask=<question>&goal=<endgoal>
```

`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.