How to Upgrade Your Project to Unity 6 (Without Breaking It)

Unity 6 is the current long-term support line, and sooner or later every project on 2021 or 2022 LTS has to make the jump. The upgrade itself is one click in Unity Hub. What takes the time is everything after it: obsolete-API warnings, a URP renderer feature that stopped drawing, a package that won’t resolve, and physics code whose property names changed. This guide is a practical checklist for upgrading an existing project to Unity 6: how to prepare, what to click, and how to fix the breaking changes people actually hit.

Should You Upgrade?

Unity 6 (editor versions starting with 6000.) brings a faster URP with Render Graph, GPU Resident Drawer for big scenes, Build Profiles, better multiplayer tooling, and years of support ahead. For a project in early or mid development, upgrading is usually worth it. For a game a few weeks from release, it usually isn’t. Ship on the LTS you tested on and upgrade afterward.

If you’re unsure which version fits your project, our guide on which Unity version to use covers the tradeoffs.

Before You Start

1. Commit everything to version control. The upgrade rewrites a lot of assets and project settings. With Git you can see exactly what changed and roll back in seconds. No version control? Copy the whole project folder first. (Our Git for Unity guide takes about 20 minutes to set up.)
2. Get to a clean state. Fix existing compiler errors and warnings in your current version. Upgrading a project that already has errors makes it very hard to tell what the upgrade broke.
3. Update packages in the old version first. In Package Manager, move packages to the newest version your current editor supports. That makes the jump smaller.
4. List your Asset Store assets. Check each one’s store page for Unity 6 support. Abandoned assets with editor scripts are the most common source of upgrade errors.
5. Very old projects: coming from 2020 or earlier, upgrade to 2022.3 LTS first, fix everything, then go to Unity 6. Two smaller steps are easier to debug than one big one.

Doing the Upgrade

1. Install the latest Unity 6 release in Unity Hub > Installs, with the same platform modules you use now (Android, iOS, Web and so on).
2. In Projects, click the editor version next to your project and pick the Unity 6 version. Hub warns that the project will be upgraded. Confirm.
3. The first import takes a while because the Library folder is rebuilt from scratch.
4. If your scripts use outdated APIs, the API Updater asks to rewrite them automatically. With your work committed, choose I Made a Backup. Go Ahead! It handles simple renames for you.
5. If Unity offers to open in Safe Mode because of compile errors, accept it. Safe Mode loads the project without importing assets until your code compiles, which is faster to fix.

Common API Changes

These are the changes that show up as warnings or errors in most upgraded projects. Most are renames, and the API Updater handles many of them, but not in every case (for example, in assemblies it can’t write to).

Rigidbody velocity and drag

In Unity 6, Rigidbody.velocity became linearVelocity, drag became linearDamping, and angularDrag became angularDamping. The same applies to Rigidbody2D.

// Before
rb.velocity = new Vector3(0, jumpForce, 0);
rb.drag = 2f;

// Unity 6
rb.linearVelocity = new Vector3(0, jumpForce, 0);
rb.linearDamping = 2f;

FindObjectOfType

FindObjectOfType and FindObjectsOfType are obsolete. Their replacements make you choose whether you need sorting, which is the slow part:

// Before
var gm = FindObjectOfType<GameManager>();
var enemies = FindObjectsOfType<Enemy>();

// Unity 6
var gm = FindFirstObjectByType<GameManager>();   // or FindAnyObjectByType (faster)
var enemies = FindObjectsByType<Enemy>(FindObjectsSortMode.None);

Use FindAnyObjectByType when there’s only one instance anyway. It skips the ordering work.

Obsolete warnings you can leave for later

A warning (yellow) doesn’t block anything. Fix errors (red) first, make a build, and then work through the warnings in batches. Don’t try to fix 300 warnings before you’ve confirmed the game runs.

Packages to Update

Open Window > Package Manager, filter to In Project, and look for the update arrows. Packages that commonly need attention:

• Cinemachine 3. The upgrade from 2.x changes the namespace to Unity.Cinemachine and renames components (CinemachineVirtualCamera becomes CinemachineCamera). There’s an upgrader in the Cinemachine menu. See our Cinemachine 3 guide.
• AI Navigation. NavMesh baking now uses the NavMeshSurface component from the AI Navigation package. Old baked data keeps working, but rebaking needs the package. See our NavMesh tutorial.
• Input System, TextMesh Pro, Timeline: update to the versions Package Manager recommends. In Unity 6, TextMesh Pro is part of the Unity UI package, so the separate TMP package may disappear from your list. That’s expected.
• Git or local packages pinned to a specific commit won’t update themselves. Check their repositories for a Unity 6 branch.

URP and Render Graph

The biggest change for URP projects is Render Graph, which is on by default in Unity 6. Built-in effects and URP’s own passes are already converted. What breaks is custom Renderer Features written for older URP versions using Execute and ScriptableRenderPass without a RecordRenderGraph method.

You have two options:

• Short term: in Project Settings > Graphics, under the URP section, enable Compatibility Mode (Render Graph Disabled). Old renderer features work again. Unity treats this mode as a transition aid, not a long-term setting.
• Long term: port each custom pass to implement RecordRenderGraph. Asset Store assets with renderer features (outlines, fog, custom post effects) usually have updated versions that already do this.

If materials turn pink after the upgrade, a package with custom shaders probably needs an update. Our pink materials guide covers the fixes. Effects that stopped showing are covered in URP post-processing not working.

Build Profiles and Platforms

The old Build Settings window is now File > Build Profiles. Your existing platform and scene list carry over as the platform’s default profile. You can add extra profiles, for example a “Demo” profile with a different scene list and scripting defines, without editing settings by hand before each build.

A few platform notes:

• The WebGL platform is now called Web in the editor. Existing WebGL settings carry over.
• Android builds pick up newer Gradle, SDK and target API versions. If a build fails after upgrading, see our Android Gradle build fixes.
• For Unity Personal, the Made with Unity splash screen is optional in Unity 6.

Testing After the Upgrade

1. Clear the Console and check it compiles with zero errors.
2. Open and play every scene in your build list, not just the main one. Missing script references and pink materials often hide in rarely opened scenes.
3. Make a real build on every target platform. Some problems (shader stripping, IL2CPP, Android Gradle) only show up in builds.
4. Compare performance with the Profiler against a build from the old version. Unity 6 is often faster, but a changed setting can make it slower.
5. Commit the upgraded project as its own commit, so the upgrade is easy to find in history later.

Troubleshooting

“Rigidbody.velocity is obsolete: use linearVelocity”

Rename to linearVelocity. Do the same for drag (linearDamping) and angularDrag (angularDamping).

“The type or namespace name ‘CinemachineVirtualCamera’ could not be found”

Cinemachine 3 was installed. Either run its upgrader and switch to CinemachineCamera with using Unity.Cinemachine;, or pin Cinemachine 2.x in Package Manager for now.

Custom renderer feature does nothing, or a warning about Render Graph

The pass has no RecordRenderGraph implementation. Enable Compatibility Mode temporarily and port the pass, or update the asset that provides it.

Package Manager errors: “Unable to add package” or dependency conflicts

Remove the conflicting packages, let the project compile, then re-add them at their latest versions. Delete Packages/packages-lock.json if a lock entry pins an incompatible version. It will be regenerated.

Scripts show “missing” on objects after the upgrade

A script failed to compile or a package renamed its classes. Fix compile errors first. If references are still missing, see our missing script references guide.

Upgrade takes forever or crashes on import

Close the editor, delete the Library folder (it’s regenerated) and reopen. If one asset crashes the import every time, the Editor log (Console > Open Editor Log) names the last file processed.

FAQ