Unity SDK: UPM vs Asset Package Install Guide
A Unity SDK can be installed either through Unity Package Manager (UPM) or as a traditional asset package (.unitypackage). Starting with SDK version 4.6.4, UPM is the preferred distribution method, but both remain supported. This guide explains the trade-offs, the migration steps, and the testing approach so you can pick the right path for your project.
Asset package vs Unity Package Manager
An asset package is a compressed file containing Unity assets such as images, textures, or scripts. Importing it adds those assets directly to your project's Assets directory. It is simple to import but has drawbacks: no version management, no dependency management, and dependencies live alongside your own assets, so they can be accidentally modified.
Unity Package Manager, released by Unity in 2017, is based on npm and distributes packages through a registry. It provides version management, dependency management, and keeps dependencies separate from the rest of your project. The SDK package is published via the OpenUPM registry, which you add in Project Settings > Package Manager.
UPM is recommended, but both systems remain available. Use the checklist below to decide.
Decision checklist
Use this checklist to choose between UPM and the asset package:
- Do you need automatic version tracking and updates? → UPM.
- Do you want dependency isolation from your own assets? → UPM.
- Are you already using other UPM packages and want a consistent workflow? → UPM.
- Do you need the simplest possible import with no registry setup? → Asset package.
- Are you unable to add the OpenUPM registry to your project? → Asset package.
- Do you need to avoid manually downloading EDM4U? → Asset package includes EDM4U automatically; UPM requires a separate EDM4U download.
Migration steps to support UPM
To make the SDK compatible with UPM while still allowing asset package use, the team followed Unity's documented process. The key additions were:
- A package manifest containing package information such as version number and changelog links.
- Assembly definition files in the folders containing the SDK scripts, which lets developers access the scripts in a more organized way.
After those changes, two additional problems had to be solved: the EDM4U dependency and testing both distribution systems.
Google's External Dependencies Manager for Unity (EDM4U)
The SDK depends on Google's External Dependencies Manager for Unity (EDM4U), which resolves dependencies with the iOS and Android SDKs on each platform. Google officially distributes EDM4U only as an asset package, not through any UPM registry.
When the SDK is distributed as an asset package, EDM4U is included. When using UPM, developers must download the EDM4U asset package and add it to their project manually. A specific EDM4U version may not work with the SDK. There are plans to add Unity Editor functionality to download the library and ensure it matches the SDK version.
Testing both distribution systems
The SDK maintains automated API tests to ensure its API cannot be changed by accident. Because two distribution systems are supported, both must be tested reliably.
The test setup uses two Unity projects:
- Subtester – imports the SDK via a local UPM package (so it gets the latest changes immediately), runs automated API tests, and exports the asset package used by the other project.
- IntegrationTests – imports the SDK using the asset package generated from Subtester and runs automated API tests.
A script runs during automation to prepare Subtester for asset package export: it adds the SDK sources as project assets, removes the UPM dependency (to avoid duplicated sources from the assets and from UPM), downloads the latest EDM4U, and creates an asset package containing both the SDK and EDM4U.
This setup ensures both distribution paths are exercised and that the API remains stable.
Failure distinction: duplicate sources vs missing EDM4U
Two common issues can arise when mixing distribution methods:
- Duplicate source collision: Adding the same sources multiple times to the same project causes collision errors in Unity. In the export workflow, the script must remove the UPM dependency before adding sources as assets, otherwise the project won't compile because of duplicated sources (from the assets and from UPM).
- Missing or mismatched EDM4U: When using UPM, EDM4U is not automatically included. Developers must download the EDM4U asset package and add it to their project. A specific EDM4U version may not work with the SDK.
OpenUPM vs npm registry
OpenUPM was chosen over npm's official registry for two reasons: OpenUPM has automations that detect new SDK versions released on GitHub, so the team avoids building its own publishing automations; and OpenUPM is oriented toward Unity developers, whereas npmjs is broader. The decision may be revisited in the future, or the package could be published to both.
Adding the OpenUPM registry in Unity
To install the SDK through UPM, add the OpenUPM registry to your project in Project Settings > Package Manager. The exact registry URL and scope values are provided in the Unity SDK installation docs, which you should follow for the current setup steps. After adding the registry, you can install the package through the Package Manager window.
Frequently asked questions
Can I still use the .unitypackage asset instead of UPM?
Yes. The asset package remains available. You can download it from the Unity SDK GitHub releases page and import it into your project. UPM is recommended but not required.
Why do I need to download EDM4U separately when using UPM?
Google officially distributes EDM4U only as an asset package, not through any UPM registry. When you install the SDK via UPM, EDM4U is not bundled, so you must add it manually. The asset package distribution includes EDM4U automatically.
What happens if I import the SDK both from UPM and as an asset package?
Adding the same sources multiple times to the same project causes collision errors in Unity. The test setup avoids this by removing the UPM dependency before exporting the asset package, since otherwise the project won't compile with duplicated sources from the assets and from UPM.
Which registry is used for UPM?
The Unity SDK package is published via the OpenUPM registry. You add the registry in Project Settings > Package Manager.