Important: Script compilation with MSBuild is an experimental feature in this version of Unity. It’s provided as a technical preview for functional testing and validation and is not suitable for production use.
Unity doesn’t support the use of NuGet as an alternative to the Unity Package Manager (UPM) for developing and distributing Unity Editor or Engine functionality. When you compile scripts with MSBuild, Unity restricts which NuGet packages your project can use and checks every restored package against a policy before it compiles any code.
This page describes the restrictions that apply to NuGet in a Unity project, the checks that enforce them, the errors Unity reports when a package violates the policy, and the .NET libraries that Unity bundles with the Editor.
Unity applies the following restrictions to the use of NuGet:
After every restore, Unity checks each resolved NuGet package against the following rules. A package that violates a rule fails the build before Unity compiles any code, and Unity reports the violation as a compilation error in the Console window.
| Error code | Cause |
|---|---|
MSBU0006 |
The package depends on Unity APIs, or redistributes a Unity assembly. |
MSBU0007 |
Unity blocks the package by its identity. |
Unity checks every package in the resolved dependency graph, not only the packages that your project references directly. A package that a dependency brings in transitively is subject to the same rules.
You can’t opt out of these checks. No MSBuild property, environment variable, or allowlist disables them. Unity performs the checks outside of both restore engines, so a target that uses BeforeTargets="Restore" or AfterTargets="Restore" can’t intercept them. For more information about the restore engines, refer to MSBuild Restore.
Unity performs the checks whenever it restores packages, and a build that reuses a valid restore cache skips them. A rejected build never writes that cache, so the error repeats on every subsequent build until you remove the package that caused it.
Unity rejects a package with the error MSBU0006 when any assembly that the package contributes to the build meets either of the following conditions:
UnityEngine, UnityEditor, or any assembly whose name starts with UnityEngine. or UnityEditor..NuGet has no concept of Unity versions, platforms, or module compatibility, so a package compiled against UnityEngine.dll is pinned to a single Editor version and breaks when you upgrade the Editor. Distribute code that uses Unity APIs as a UPM package or an Asset Store package instead of a NuGet package.
Unity inspects the compile-time assemblies, the runtime assemblies, and the Roslyn analyzers that a package contributes. Unity skips files that it can’t read as managed assemblies, such as native libraries and resource-only assemblies.
Unity doesn’t reject a package based on its name. Package identifiers that start with Unity., such as Unity, Unity.Container, and Unity.Abstractions, belong to an unrelated dependency injection library and are permitted, because they don’t reference Unity assemblies.
A package that references Unity APIs produces an error of the following form:
NuGet package 'Example.Package' 1.0.0 references Unity APIs (UnityEngine, UnityEngine.CoreModule) from 'Example.Package.dll', but this is not allowed. Distribute code that uses Unity APIs as an Asset Store or UPM package instead of a NuGet package. Referenced by: MyLib.csproj.
A package that redistributes a Unity assembly produces an error of the following form:
NuGet package 'Example.Package' 1.0.0 redistributes the Unity assembly 'UnityEngine' (in 'UnityEngine.dll'), but this is not allowed. Unity assemblies must not be shipped through NuGet. Referenced by: MyLib.csproj.
In both cases, the error names the package, its resolved version, the assembly that caused the violation, and the projects that reference the package. To resolve the error, remove the PackageReference from the project that the error names. If a transitive dependency caused the violation, remove or replace the direct dependency that brings it in.
Unity rejects a package with the error MSBU0007 when the identity of the package appears in Unity’s block list, whatever its assemblies contain. This list covers packages that are known to break in Unity, that have incompatible licenses, or that a UPM package supersedes. The MSBU0006 check can’t detect these cases by inspecting assemblies.
The block list is part of the Editor installation and is versioned with the Editor, so its contents can change when you upgrade to a new Editor version. There’s no per-project or per-user override, and Unity doesn’t publish the contents of the list.
An entry in the block list applies either to every version of a package or to a range of versions. The error names the resolved version and, where the entry blocks a range, the blocked range, so that you can determine whether an upgrade resolves the error:
NuGet package 'Example.Package' 1.4.2 is blocked and violates Unity's NuGet package policy. Blocked versions: (< 2.0.0). Referenced by: MyLib.csproj.
To resolve the error, upgrade the package to a version outside the blocked range if the error names one, or remove the PackageReference and use a supported alternative.
Note: Unity reports only the first rule that a package violates. A package that Unity blocks by identity reports MSBU0007 only, even when it also depends on Unity APIs.
Unity bundles specific versions of several .NET libraries with an Editor installation. These versions are dependencies for certain Unity features, and are chosen to align with Unity’s internal .NET runtime version.
In the .NET assembly model, it’s not possible to have two versions of the same package present at once. If you add your own copy of one of these packages, Unity discards it and uses its own bundled version instead.
Unity also resolves a package that depends on a different version of one of these libraries against its own version. In most cases this is transparent, but if your dependency requires an API surface that isn’t present in Unity’s version, you might encounter incompatibilities.