Search Unity

By now, you’ve noticed a plan for Unity involving packages, which has been steadily moving forward. The story kicked off with the ProBuilder announcement, and we’ve since followed up by introducing features of the Package Manager and improved Unity Project Management. Now, let’s dive a little deeper into the story.

Packages, what are they?

Packages will be everything. In the future, we expect to carve apart Unity into many pieces, each of which you will be able to update, experiment with and modify. All our new features are already planned to be delivered in this way: Scriptable Render Pipelines, Entity Component System (ECS), CineMachine, and so on.

Additionally, much of what lives in GitHub repos (NavMesh, Recorder, …), extensions ( GUI system, Networking, Timeline, etc.), and various Unity developed Asset Store packages will now be migrated into packages.

We are dogfooding our own tech, and once the system feels solid and robust, we will open the door for Asset Store publishers as well as general users to get in on the packages story in the future.

The main benefits of moving to packages revolve around speed, modularity and customer choice, and we aim to achieve this by making them:

  • Referenceable or Embeddable
    • Referenced, without needing to explicitly move/add files
    • Embeddable, take a snapshot copy to have direct access to modify
  • Extendable
    • Access to source repos (where feasible)
    • Ability to upstream and downstream changes
  • Easy to update
    • User interface makes it easy to see choices on versions and compatibility
  • Automatic and explicit dependencies
    • Clear dependency visibility and automatic dependency resolution
  • Optional
    • The ability to add or remove as desired (allowing for dependencies)

How do packages work?

We expect packages to have a set of files that can be “virtually dropped” into your project where they will simply work. They can then be referenced from your game assets and scripts as needed. Each package has a definition file (package.json) that defines the version, lists explicit dependencies on other packages and the earliest version of Unity that supports the package.

Packages may contain:

  • Regular assets
  • Scripts
  • Documentation
  • Tests

How are these different from Asset Store packages?

Asset Store Package New Package
File .unitypackage Git repo or .tgz
Location Imported to Asset Folder Referenced (or embedded) via Packages folder
Dependencies Manual Explicit and calculable
Removal Manual / Difficult Remove Reference or delete embedded directory
Updatable Error prone / Difficult Easy
Forkable Manual Easy, source available (when feasible)
Full Projects Difficult to install Templates from New Project dialog

Packages Life Cycle

We are aiming to keep the package concept very simple, and fundamentally there are only two real states to consider:

  • Preview == Not Production Ready, Use at your own risk.
  • Released == Production Ready, fully supported.

One IMPORTANT extra label we apply to specific Released versions is “Verified For XXXX.Y,” indicating that a collection of specific released packages has been tested in one of the Unity release cycles.


This phase is idea genesis, early development, massive re-work, or in the midst of a complete update on a package. This is where development is the rawest, and changes can be significant.

From our point of view, we are exposing the direct development of our systems to the users, who can influence the direction and offer constructive feedback as things are built. In turn, it’s the riskiest place to be in terms of trying things out. You wouldn’t want to rely on a package in preview for your project, unless you’re also ready to fork and maintain things for yourself.

Versions in Preview are expected to precede the major.minor.patch version it lists. For example, this is a sequence you might see:






Some teams may also follow:





Both are acceptable, but the former has the clarity of no missed “Released” versions in between. (Arguably, 0 is by default preview versions, but we aim to be explicit.)


A package that’s had success in preview and shows promise with the users can move to release where it gets all the polish in place. While in release, we expect the Patch version of the package to be mostly updated for bugs and tweaks, with perhaps occasional minor version bumps with small improvements. The important part is to never introduce backwards-incompatible changes during a given major version release, which would require a return to Preview for that new major version.

At this point, we expect a Unity-developed package to have:

  • Reasonable test coverage
  • 100% API documentation coverage
  • Basic user manual documentation
  • API reviews for
    • Naming conventions
    • Security issues
    • Upgrade issues
  • Passed our package validation tests
    • Checks for versioning
    • Checks for import errors

Verified For XXXX.Y

Verified For is not a state, but as per Unity Version labels, we may apply to a released package. So a specific package, for example, com.unity.postprocessing at version 2.0.0, could be “Verified for 2018.1” and “Verified for 2018.2” if nothing changed between those releases, and it has passed through the Unity release testing cycle.

The Verified For label is something that can only be attached after a full Unity release testing cycle. What does that mean? Please read on.

Ok, what is a Unity release then?

Now that we explained the lifecycle of packages, let’s dive into what Unity releases will become. Unity will slowly be shedding functionality from the core into separate packaging with clear dependencies on Unity versions as required by the APIs.

As the numbers of packages proliferate, and with each package released individually, it will become harder to test the large combinations of what is available. So we will focus on a clear “verified for XXXX.Y” snapshot set that has been tested in concert for a Unity cycle.

This means, at the start of the Unity cycle, we will have picked the set of released packages we believe are in good standing in their candidacy, in other words, packages that have stabilized and are not under active development. These will be entered together to our builds, offered to Release QA, and tested together for the full cycle.

Timing is crucial on packages joining the set. Effectively, the start of the cycle means we’ve boarded the plane and pushed back from the gate. There’s no room for late additions before the flight takes off. With this rigor, we will test our utmost to ensure that all included packages are compatible with each other within the set. In some cases, we may find an unruly package, and drop it from the final set before release as testing progresses.

Wait, so many packages! That sounds like a lot of confusion!

To help navigate the proliferation of packages, we added the new Package Manager UI to Unity 2018.1. We are still improving and refining this Unity Editor window, but this will help you browse, view information and choose what packages you want to include in your project.

We’re also bringing in Project Templates, which are packages that are structured in useful configurations, which you can find on your Hub or Launcher. Project Templates include relevant packages to get you started in the right way for a given purpose. In the future, we expect Asset Store publishers to create new templates, as well as studios and users themselves.

Of course, every Unity release will still come with a default set of packages that we consider tested, useful and available with any new project created. As stated, one can always opt out of these selections, and still get  the general Unity features and functionality you know and love.

Going forward

It’s an exciting time for Unity in this transition. Our R&D is excited to be aligning ourselves closer to you all, the game developers, and to share more development, features, and choices at a faster pace. I hope you all look forward to the packages to come!


Q: Can two versions of the same package be present in the same project?

No, the project owner must resolve the issue by deciding which one  is used and then testing how things work. Unity will add some intelligent automatic conflict resolution similar to NuGet’s. However, it still ultimately boils down to the project owner’s choice.

Q: Can a package be in multiple different states in the Package Manager?

Yes, for example, after a package has been released, a newer Preview version may become available with new features. The Package Manager will list all available known-compatible versions of a package for the editor used.

Q: Can multiple packages affect the same things and potentially cause a conflict?

Yes. We don’t have any examples of that yet, but it is something we do expect to occur.

Q: Can I downgrade a package to a prior version?

Possibly, but this is generally not recommended or supported. We intend to support the semver spec, and trying to step down a major or minor version may cause you to lose functionality, compatibility, and in the worst case scenario, introduce fatal crashes (for example due to utilizing older/non-existent APIs in later versions of Unity). Downgrading to a prior patch release may be safe, but it should be tested individually for your use. (As always, backup before testing.)

Q: Where do packages go in my project?

They’re referenced in the project manifest JSON file, but the actual files are elsewhere on your machine. A new person opening the project on a new machine may invoke a download to get that correct package at the specified version onto their machine to be utilized by the project.

Q: How do you override a package?

We haven’t yet finalized the details and functionality, but the general plan is to have a couple options:

  • Embed a package, taking a snapshot of it and laying a copy of those exact files into your project (not in the Assets folder, but in the Packages directory)
    • This option is useful for immediate fixes or similar temporary experiments
    • The project version takes precedence over the cache
  • Clone the source repo, git sub repo/submodule into your project
    • Implementation is still in the works but allows you to fork, branch, merge changes coming downstream or even offer fixes upstream

Q: Does Package Manager automatically resolve and download dependencies?

Yes! However, clear conflict resolution display and choice is not yet implemented.

Q: Does upgrading completely replace the previous package?

Effectively yes. The new set of files in the new package version are pointed to, although any changes the package made to the Assets folder would remain. This is an advantage over the old unitypackage, which pushed things into the Assets folder and made it difficult to upgrade.

27 replies on “Unity Packages Life Cycle”

Now that all unity modules are separated into packages, Does unity strip unused packages automatically when built? Say If I don’t use Terrain in my game does terrain component gets stripped off the build?

Also Whats the smallest apk size we can achieve if all components are stripped? I tried stripping all the components except Core component in 2018.2 Beta and the build size was 5.99mb and webgl was 2mb. can we go further and make empty apk even smaller?

How will it handle packages that depend on others and one of those is a paid package?

We’re hoping to integrate the package server with the information about which packages you’ve purchased, so if you own the paid package it will just download automatically, and if you don’t then… it won’t :) For sure we will need to make sure there’s a good UX around all of that.

In the future it is said this will support Asset Store packages – if so, can one select which files from the asset store package to use? Generally one doesn’t want to include example folders from the package that show how it can be implemented (Adventure Creator, Dialogue System and others use this feature) because it would bloat the build.

All the details of exactly how that will work are still to be decided, but we know about that kind of thing. There’s multiple possible options, including e.g. turning Asset Store packages into multiple packages (one for the core asset, one for examples).

Can a package contain prefabs?
If an older version of a package become obsolete, can people still download the old version?
Is there a way to set auto-update to a package?
And can we, like in the asset store, use URI link to open package details in the editor?


A lot of corporations block access to other ports than HTTP, seems the package manager is using 443. This basically prevents them from using 2018.1 and forward, as the Package Manager can’t find any packages and crashes on trying to resolve the manifest. I had to experience that first-hand on a client setup and we had to revert back to 2018.1.0b10, which doesn’t crash.

Any plans to give a fallback option for downloading packages in such limited environments?

443 is HTTPS – I would be very surprised if there are actually that many corporations out there who permit HTTP only if it is unsecured.

That said, yes, we are working on solutions for ‘closed network’ environments.

The port just shows in the error message Unity throws, maybe it’s just a sideeffect of the actual internal block. You can send me a PM or mail and we can discuss further, it’s a pretty serious issue right now.

Remember that if the UPM provides several android plugins in the future they will collide and we will have to do manual work. This also will be great on Continuos Integration pipelines.

I don’t understand much. but you should not make it is more complex

If you don’t fully support “multiple versions in same project”, then you MUST fully support “downgrading always works exactly as well as upgrading does”. This isn’t negotiable: we have 30+ years of package managers that show one of these features is always essential (you can pick which one!).

Please don’t pretend that “source control makes it OK”. We already have the problem that by the time you install Asset X, you find you’ve been using incompatible versions of Asset Y for several months and source control is useless: you cannot simply roll-back 3 months of work (deleting it!) in order to satisfy compatibilty. Don’t make this worse, please!

Since you’ve said that UI System will now be available via package, can it get some love and finally get some new features/fixes? There’s many PR’s on Bitbucket lying there for years and you haven’t accepted any. Scroll Rect takes massive amounts of CPU and seems like the only commits which are accepted are new version tags, that’s all. If you won’t update it just please make it so that we (Users) can manually change the source code.

If I understood it correctly, instead of making a unitypackage file I will be able to share my own creations simply by providing a link (or something like that) of my GitHub repo? GitHub link registered into a website that manages packages?

Will it be possible to have private repos (on git or on a local server) to provide packages? Say, proprietary packages developed for a company.

Two thoughts:

1. As the pieces are carved apart, will this mean smaller build sizes because packages that are not loaded are not in the build?

2. Can you have different packages for different projects within the same Unity install?

1. Probably not much, because in practice we _already_ strip out parts of the engine that you are not using (on platforms that support stripping, anyway). If you’re building for a platform like iOS, and you’re not using, say, 2D Physics, then the 2D physics module should not be in your build. There’s even a new API in 2018.1 that lets you find out which engine modules were included in your build and why. So, shipping something as a package rather than ‘built in’ to the engine just means that it changes from ‘included by default, then stripped’ to ‘excluded by default, then included if you add the package’ – the end result doesn’t change much.

2. Yes, the list of packages to use is stored on a per-project basis, not per-install, so you can absolutely have project A that has one list of packages and project B that has a different list.

Comments are closed.