Upgrading your project gives you access to the latest features, improvements, and bug fixes introduced in a newer version of the Unity Editor.
This page details some recommended best practices to upgrade your project. However, how you apply those practices to your project depends on the circumstance of your project. The experience of upgrading your project can vary widely depending on several factors such as:
The recommended best practice is to upgrade your project sequentially from one major version to the next. For example, if you’re upgrading from 2020 LTS to 2022, you should first upgrade to 2021 LTS, then to 2022 LTS. If you upgrade your project from a much older version straight to a newer version, you might encounter more issues than if you upgrade your project sequentially.
To upgrade your Unity project to a newer version of the Unity Editor:
Before you upgrade your project, make sure that the advantages of upgrading outweigh the effort required to upgrade for your specific case. Large, complex projects with several third-party assets and packages attached might take a long time to upgrade and require significant changes.
If your project uses many third-party packages and assets, refer to their documentation to check if they’re compatible with the version of the Unity Editor you’re upgrading to. If they’re not compatible with your target version of the Unity Editor, you might need to find an alternative solution or update the assets yourself. Consider reaching out to the asset publishers for support.
For help with upgrading, refer to:
Before you update your project, it’s crucial that you back up your project files. A backup ensures that you can revert to the previous version of your project if you have any issues during the upgrade process. You can also use a backup to compare the performance of your upgraded project against the previous version. The recommended best practice to back up your project is to use version controlA system for managing file changes. You can use Unity in conjunction with most common version control tools, including Perforce, Git, Mercurial and PlasticSCM. More info
See in Glossary.
If you’re not using version control, you can manually back up your project by copying the project folder to another location on your computer or an external drive. In most scenarios, using a version control system is better than manually backing up your project files.
Tip: If you’re manually backing up your project, you can exclude some auto-generated folders such as the Library folder to save disk space. The Library folder is regenerated when you open the project in the Unity Editor.
To prepare your project for upgrade:
Using the Hub is the recommended best practice to install the Unity Editor, create projects, and manage your Unity experience. The Hub provides a central location to manage your Editor installations, accounts, licenses, and projects. To install the newest version of Unity Editor in the Hub, refer to Install and uninstall Editor versions.
Make sure you install the same modules that you used in the project you are upgrading.
To learn other ways to install the Unity Editor, refer to Install Unity.
To manually install a specific version of the Unity Editor, you can also refer to the Unity Download Archive.
To open your project in the new version of the Unity Editor:
Tip: You can also select Install Other Editor Version in the Installs window to install a different version of the Unity Editor.
When you upgrade your project to a new version of the Unity Editor, you might encounter compatibility issues and deprecations introduced in the new version.
Tip: If you run into an issue that’s not covered in the release documentation, you can ask for help from the wider Unity community at Unity Discussions.
To resolve compatibility issues, open the project in Safe Mode, and do the following:
.unitypackage extension. Asset packages are a handy way of sharing and re-using Unity projects and collections of assets. More infoTest your project to ensure that it works as expected in the new version of the Unity Editor:
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.