UnityNuGet feeds NuGet packages into the Unity Package Manager

A scoped registry, not a NuGet client

UnityNuGet provides a service to install NuGet packages into a Unity project via the Unity Package Manager, and the README describes it as a smooth integration of a curated list of NuGet packages within the Unity Package Manager.

The mechanism is a UPM scoped registry. Unity's Package Manager can talk to a registry that serves packages, and UnityNuGet is one such registry that translates between the NuGet format and the UPM format. The scope is org.nuget, so any package you add from it carries that prefix in the Package Manager window, and the README shows the packages appearing with a (NuGet) postfix so you can tell them apart from Unity packages.

Two things follow from the design. First, this is a registry, not a client, so nothing in your project changes to use it: you add a registry entry and Unity does the rest. Second, the feed is curated, which is the single most important fact about the project.

The service is hosted on OpenUPM infrastructure at unitynuget-registry.openupm.com, and the README notes the feed is provided by OpenUPM. There is also a public demo site, a server status badge and a server feed badge at the top of the README.

The project is BSD-2-Clause licensed, written in C#, and the README is explicit that it is not an official service provided by Unity Technologies Inc.

Adding the registry, by hand or through the UI

Using the service means adding a scoped registry, and the README gives two routes.

The first is to edit the project's Packages/manifest.json by hand:

{
  "scopedRegistries": [
    // Other registries...
    {
      "name": "Unity NuGet",
      "url": "https://unitynuget-registry.openupm.com",
      "scopes": [
        "org.nuget"
      ]
    }
  ],
  "dependencies": {
    // Other dependencies...
    "org.nuget.scriban": "2.1.0"
  }
}

The second route is the Package Manager UI, following Unity's own instructions, with the name Unity NuGet, the url of the registry and the scope org.nuget.

Either way the dependency entry in the manifest is what actually pulls the package in, and the package name carries the org.nuget prefix.

The registry service and the tool that runs on the server are separate pieces, and the NuGet package UnityNuGet.Tool is published on nuget.org for the server side.

Assembly version validation is the setting that breaks it

The step that decides whether this works for you is called Disable Assembly Version Validation in the README, and the reason is specific.

It is necessary to ensure that binding redirects for strongly named assemblies in NuGet packages resolve correctly to paths within the Unity project. If the redirect points somewhere outside the project, Unity refuses to load the assembly and you get compilation errors that have nothing to do with your code.

In Unity 2022.2 and later this is the default behaviour, so no action is required. For earlier versions, the instruction is to uncheck Project Settings, then Player, then Other Settings, then Configuration, then Assembly Version Validation.

That is a one setting change, and it is the kind of thing that silently costs an afternoon if you do not know it is coming. The alternative to changing the setting is to keep the setting and accept that some strongly named packages will not resolve.

Cache and timeout are the two failure modes

The troubleshooting notes in the README are short and cover the two problems that actually come up.

The first is a stale cache. If you are encountering weird compilation errors with UnityNuGet and you have been using UnityNuGet already, it could be that packages have been updated on the server, and in that case you need to clear the cache containing all the Unity NPM packages downloaded from the registry. On Windows that cache lives at %LOCALAPPDATA%\Unity\cache\npm, and Unity's documentation lists the locations per operating system.

The second is a timeout, with the error message given as a Package Manager Window error adding a package followed by a connect ETIMEDOUT line and an internal UnityEditor call. The fix is to verify that you are using the new OpenUPM-based URL and not the old Azure Websites URL, and to check the OpenUPM status page in case the platform itself is having an outage.

Both of these are the kind of problem that looks like a project bug and is actually a cache or an upstream outage, which is worth knowing before you file an issue.

The curated list has entry rules, and transitive dependencies matter

The service provides only a curated list of NuGet packages, and the registry is a single file, registry.json, at the repository root. Adding a package means sending a pull request that modifies that file, keeping the alphabetical order and the format.

The constraints for inclusion are specific. The package must have non-preview versions, for example 1.0.0 and not 1.0.0-preview.1. It must provide at least .NETStandard2.0 assemblies, optionally .NETStandard2.1 as well. And the contributor must specify the lowest version of the package that supports .NETStandard2.0 upward, so that packages depending on it have a chance to work.

The rule that catches people out is the last one in the list. All transitive dependencies of the package must be explicitly listed in the registry as well. A package that depends on something not in the list will install and then fail to load its dependency at runtime.

There are also two editorial notes. The project reserves the right to decline a package, so a pull request is not guaranteed to be accepted. And the server is updated only when a new version tag is pushed on the main branch, which means the registry contents lag the NuGet feed by however long that takes.

Self hosting on your own container platform

For more control over the server, the README recommends hosting the service yourself, and the reason given is practical: you can decide which specific packages to include in registry.json, which makes the server lighter.

A Docker image is published in ghcr.io, and the README lists the places you can run it, with a complete example in examples/docker. The listed targets are local Docker, Azure Container Apps, AWS Fargate and Google Cloud Run, which covers the usual serverless and managed container options.

The Dockerfile in the repository shows the shape of the service. It is a two stage build on the .NET 10 SDK and ASP.NET runtime images, both pinned by digest, with the build stage restoring and publishing UnityNuGet.Server for the target architecture and the runtime stage copying the output in. The runtime image also installs the upm-cli tool, but only on linux/amd64, because the linux/arm64 images do not support that tool.

That last detail is the kind of thing that decides where you can run it, since it also means the Apple silicon route to Cloud Run is not available for a build that needs package signing.

Package signing and private feeds

Signing is optional and uses the upm pack command. When the required environment variables are set, the packages are signed automatically, and the README names them: Signing:UpmServiceAccountKeyId, Signing:UpmServiceAccountKeySecret and Signing:UnityOrganizationId.

The variables are the ones Unity's own documentation defines in the Prerequisites section for the upm-cli, so the setup is the same one you would follow for any other UPM signing workflow.

A second optional piece is private NuGet feeds. The Azure DevOps personal access token must have Packaging (Read) permissions, and the approach is to provide a custom NuGet.Config file, which the example documents.

So the service is not restricted to public packages. A team with an internal feed can point the registry at it, provided the credential has read access and nothing else.

The compatibility position is stated with the right caveats, though. The service is only compatible with Unity 2019.1 and potentially with newer versions, it is currently tested with Unity 2019.x, 2020.x, 2021.x, 2022.x, 2023.x and 6000.0.x, and it may not work with a more recent version of Unity.

Editorial conclusion

UnityNuGet suits a Unity team that needs a specific.NET library inside the editor and would rather install it through the Package Manager than drop DLLs into the project, since the registry handles the download and the assembly resolution. It is the wrong tool if you need the whole NuGet feed, because the service deliberately exposes only a curated list, and it may not work on Unity versions newer than those tested. Before adopting it, add the scoped registry to your manifest, check the assembly version validation setting for your Unity version, and confirm the packages you need are on the registry and that their transitive dependencies are listed too.

Frequently asked questions

Official sources

1. bdovaz/UnityNuGet on GitHub
2. Issues
3. License: BSD-2-Clause
4. README