Unity Package Manager

A package is a container that holds any combination of Assets, Shaders, Textures, plug-ins, icons, and scripts that enhance various parts of your Project, including Unity modules (such as Physics or Animation). Unity packages are newer, more tightly integrated versions of Asset Store packages, able to deliver a wide range of enhancements to Unity.

Use the Unity Package Manager (in Unity’s top menu: Window > Package Manager) to view which packages are available for installation or already installed in your Project. In addition, you can use this window to see which versions are available, and install, remove, disable, or update packages for each Project.

Packages window

The Packages window displays:

  • (A) The Add package from disk button, which allows you to specify the location of an external package.
  • (B) The package scope drop-down menu, which allows you to filter which packages appear in the list.
  • (C) The Advanced button, which allows you to display preview packages in addition to packages that have been verified to work with Unity.
  • (D) The search box, which allows you to look for packages by name.
  • (E) The packages list view, which displays all packages that match the filter and search parameters you specify.
  • (F) The package-specific detail view, which displays information specific to the package selected in the list.
  • (G) The status bar, which displays messages about the package load status and warnings about the network.

Specifying a local package location

The Package Manager can load a package from anywhere on your computer even if you saved it outside your Unity Project folder. For example, if you have a package called com.unity.my-local-package and you save it on the Desktop but your Unity Project is under the Documents folder.

To load a package from your local disk:

  1. Click the plus (+) icon in the status bar.

    The Add package from disk button appears.

    Add package from disk button

  2. Click the Add package from disk button to bring up a file browser.
  3. Navigate to the folder root of your local package.

  4. Double-click the package.json file in the file browser.

    The file browser closes and the package now appears in the package list with the local tag.

Filtering the list

To change which packages appear in the list, select the scope you want from the drop-down menu in the left-hand corner of the Packages window.

You can select from these options:

  • The All packages scope (the default) displays all packages on the package registry, regardless of whether they are already installed in your Project. This also includes local packages (which are always installed).
  • The In Project scope displays all packages currently installed in your Project, including local packages.
  • The Built-in packages scope displays only built-in Unity packages.

When you select a new scope, your choice appears on the package scope drop-down menu and the list displays the packages matching your choice.

Note: If you entered any text in the search box, the list only displays packages which match both the scope and the search criteria.

Advanced button

The Advanced button opens a drop-down menu that allows you to show preview packages. Preview packages are not verified to work with Unity and might be unstable. They are not supported in production environments.

To show the preview packages that are available, click the Advanced button, then click the Show preview packages menu item.

Searching for packages

You can use the search box at the top of the Packages window to find any packages that match the text you enter. The Package Manager updates the package list as you enter text, displaying every package within the current scope that matches. For example, if you enter web in the search box, the list displays different results depending on whether you chose the Built-in packages scope or the All packages scope:

Built-in package scope

You can look for a package by its package name, its tag name, or its package version number. The Package Manager analyzes the text that you enter to detect which method you are using and updates the list of packages dynamically.

Package name

You can search for either the display name as it appears in the Packages window or the registered package name that begins with com.unity.

Your search text could match the beginning, middle, or end of the package's name.

Tag name

To search by tag name, enter one of the package version tags. For example, if you enter verified in the search box, only packages with a verified tag appear, regardless of their package name.

Version number

Enter the version number in version order (MAJOR.MINOR.PATCH). For example, typing 1 returns all packages with versions matching 1.x.x (for example, 1.0.0, 1.3.2, and 1.10.1 all match but not 0.1.0 ).

Finding packages

The Packages window displays the following types of Unity packages:

  • Read-only packages

    These are packages which the Package Manager downloads from the Unity package registry as needed. They are not bundled with the Project source and may have dependencies on other packages in external Projects. This type is typical of most Unity packages.

  • Local packages

    These are packages that you saved on your computer in an external location outside of your current Unity Project.

  • Built-in packages

    These represent some of the core Unity features. You can use these packages to turn Unity modules on and off.

Note: You can find out more about what each module implements in the Unity Scripting API. Each module assembly page lists which APIs the built-in package implements.

By default, the Packages window displays the list of all packages either registered in the package registry or installed locally.

The following icons located to the right of the package name show you the status of the package:

check mark A check mark indicates that the package is already installed or enabled.

download icon The download icon indicates that the installed packages have an available update.

error indicator An error icon indicates that something went wrong during installation or loading. For more advice on resolving errors, see Error messages below.

You can filter the list to display only packages installed in your Project (including local packages) or display only built-in Unity packages. You can also search for a specific package by package name, tag, or package version number.

List of versions

To view the list of versions available for a package, click the expander icon to the left of the package name.

If there are updates available, they are displayed along with the See all versions option.

Available updates list

The See all versions submenu displays all available versions.

You can select any of these versions for the current package and install that specific version using the Install or Update to button.

Available version list

Viewing package details

The pane on the right side of the Packages window displays details about the selected package.

Details pane

These details include the following information:

  • (A) The display name.
  • (B) The version number (and tag, if available)
  • (C) The links to open the package documentation page, the package change log (if available), and the license information.
  • (D) The official package name from the registry starting with com.unity..
  • (E) The author.
  • (F) A brief description.
  • (G) Package authors can include sample code in the package that you can import into your project. To import the sample code, click the Import in project button next to the sample.
  • (H) Button to install or update a package (or the Up to date message if the selected version is already installed.)
  • (I) Button to remove or disable the package.

Status bar

The Package Manager displays messages in the status bar at the bottom left of the Packages window.

There are typically three status messages that you might see. The Loading packages message appears briefly the first time you open Packman UI in a new Project. However, if the Package Manager detects a problem, such as a missing network connection, the Package Manager displays a warning in the status bar:

Network error message

You will also often see a message informing you when the last update occurred:

Update message

Version tags

Some packages display tags next to the version number. These tags convey information about that version of the package.

The Package Manager uses the following values:

Tag Meaning
Verified This package has been verified by Unity's Quality Assurance team to work with a specific version of the Editor.
Preview This package is at an early stage of the release cycle and may not have been documented and fully validated by either the development team or Unity's Quality Assurance team.
Local This package is located on your local disk but is external to your Unity Project folder.
(no tag) This package is considered production quality, which means it is fully validated, documented, supported, and incrementally updated.

Finding more information

You can find out more about a package by viewing its documentation, changelog, or license information.

To access any of these pages, click the View documentation, View changelog, or View licenses links.

The package page opens in your default browser.

Package information page

To switch back and forth between the Manual documentation, the Scripting API documentation, the Changelog, and the License information for this package, click the corresponding link at the top of the page.

Installing, removing, disabling, and updating packages

You can perform a variety of tasks through the Packages window:

Accessing the Packages window

To open the Packages window, navigate to Unity's main menu and go to Window > Package Manager.

Installing a new package

To install a new package:

  1. Open the Packages window and select All packages from the package scope drop-down menu.
  2. Select the package you want to install from the list of packages. The package information appears in the details pane.
  3. Select the version to install. For more information on available versions, see the section on the List of versions.
  4. Click the Install button. When the progress bar finishes, the new package is ready to use.

Removing an installed package

You can only remove packages which are not required by another package.

When you remove a package, any Editor or run-time functionality which it implemented is no longer available.

To remove an installed package:

  1. Open the Packages window and select In Project (or All packages) from the package scope drop-down menu.
  2. Select the package you want to remove from the list of packages. The package information appears in the details pane.
  3. Click the Remove button. When the progress bar finishes, the package disappears from the list.

You can restore a removed package from the list when you are in the All packages scope.

Disabling a built-in package

You can disable a built-in package if you don't need some modules and you want to save resources. However, when you disable a built-in package, the corresponding Unity functionality is no longer available. This results in the following:

  • If you use a Scripting API implemented by a disabled package, you get compiler errors.
  • Components implemented by the disabled built-in package are also disabled, which means you cannot add them to any GameObjects. If you have a GameObject that already has one of these components, Unity ignores them in Play mode. You can see them in the Inspector window but they are greyed out to indicate that they are not available.
  • When building a game, Unity strips all disabled components. For build targets which support engine code stripping (like WebGL, iOS, and Android), Unity doesn't add any code from a disabled built-in package.

To disable a built-in package:

  1. Open the Packages window and select Built-in packages from the package scope drop-down menu.
  2. Select the package you want to remove from the list of packages. Its information appears in the Details pane.
  3. Click the Disable button. When the progress bar finishes, the check mark no longer appears next to the built-in package and the Disable button becomes an Enable button.

To re-enable a disabled built-in package, click the Enable button.

Updating an installed package

You can update a package while in either the In Project or All mode:

  1. Open the Packages window. An arrow indicator appears next to any packages that have updates available.
  2. Select the package you want to update from the list of packages. The package information appears in the details pane.
  3. Select the version you want from the version drop-down menu.
  4. Click the Update to button.

When the progress bar finishes, the new package version information appears in the Details pane, and any new functionality is immediately available.

Error messages

The Package Manager displays error indicators when it encounters problems:

  • System-wide issues

    Error messages that appear in the status bar indicate the Package Manager has detected an issue that is not related to a specific package. For example, if the Package Manager cannot access the package registry server, it displays this message in the status bar:

    Network error message

    If your network cannot reach the package registry server, it is probably because there is a connection problem with the network. When you or your system administrator fix the network error, the status bar clears.

  • Package-specific issues

    If a specific package has a problem when loading or installing, the error icon (error indicator) appears in the package list next to the compromised package. To find out what the problem is, open the compromised package's details pane.

Understanding how packages work

In addition to its contents (Assets, Shaders, Textures, plug-ins, icons, and scripts), a Unity package contains a package manifest file. The package manifest tells Unity how to display its information page in the Packages window, and how to install the package in the Project.

It also contains several files that help manage package deployment, including the tests, samples, license, changelog, and documentation.

Manifests

There are two types of manifest files: Project manifests (manifest.json), and package manifests (package.json). Both files use JSON (JavaScript Object Notation) syntax to communicate with the Package Manager, by describing which packages are available for each Project, and what each package contains.

Project manifests

Project manifests (manifest.json) tell the Package Manager which packages and versions are available to the Project.

Project manifests support the following value:

Key JSON Type Description
dependencies Object List of packages for the Package Manager to load. These are usually packages officially registered with Unity, but may also include local packages that are external to your Unity project.

Example of a manifest.json file:

{
    "dependencies": {
        "com.unity.package-1": "1.0.0",
        "com.unity.package-2": "2.0.0",
        "com.unity.package-3": "3.0.0",
        "com.unity.my-local-package": "file:/<external_path>/com.unity.my-local-package"
    }
}

Unity stores each Project manifest in the [your_Project_root_folder]/Packages/manifest.json file.

Package manifests

The Package Manager uses package manifests (package.json) to determine which version of the package to load, and what information to display in the Packages window.

Package manifests support the following values:

Key JSON Type Description
name String The officially registered package name, following this naming convention: "com.unity.[package name]". For example, "com.unity.resourcemanager"
displayName String The package name as it appears in the Packages window. For example, "Resource Manager"
version String The package version "MAJOR.MINOR.PATCH". Unity packages follow the Semantic Versioning system. For example, "1.3.0".
unity String The Unity version that supports this package. For example, "2018.1" indicates compatibility starting with Unity version 2018.1.
description String A brief description of the package. This is the text that appears on the Details pane of the Packages window. Some special formatting character codes are supported, such as line breaks (\n) and bullets (\u25AA).
category String The category this package is in. For example, "Forces".
dependencies Object A list of packages that this package depends on, expressed as a JSON dictionary where the key is the package name and the value is the version number. Unity downloads all dependencies and loads them into the project alongside this package.

Example of a package.json file:

{
    "name": "com.unity.package-4",
    "displayName": "Package Number 4",
    "version": "2.5.1",
    "unity": "2018.2",
    "description": "This package provides X, Y, and Z. \n\nTo find out more, click the \"View documentation\" link.",
    "keywords": ["key X", "key Y", "key Z"],
    "category": "Controllers",
    "dependencies": {
        "com.unity.package-1": "1.0.0",
        "com.unity.package-2": "2.0.0",
        "com.unity.package-3": "3.0.0"
    }
}

Unity stores each package manifest in the [package_root_folder]/package.json file.

Package registry

Unity maintains a central registry of official packages that are available for distribution. When Unity loads, the Package Manager communicates with the registry, checks the Project manifest file, and displays the status of each available package in the Packages window.

When you remove a package from the Project, the Package Manager updates the Project manifest to exclude that package from the list when in In Project mode but it is still available in All packages mode because it is still in the registry.

When you install or update a package, the Package Manager downloads the package from the registry.

Technical details

Requirements

This version of Unity Package Manager is compatible with the following versions of the Unity Editor:

  • 2019.1 and later (recommended)

Documentation revision history

Date Reason
December 12, 2018 Documentation updated. Matches core package version.
October 3, 2018 Documentation updated. Image updates and minor corrections.
September 14, 2018 Documentation updated. Matches package version 2.0.1.
June 4, 2018 Documentation updated. Matches package version 2.0.0.
May 25, 2018 Documentation updated. Matches package version 1.9.9.
May 4, 2018 Documentation updated. Matches package version 1.9.8.
March 19, 2018 Documentation updated. Matches package version 1.9.0.
Feb 8, 2018 Documentation updated. Matches package version 1.7.0.
Feb 6, 2018 Documentation cleaned up. Matches package version 1.6.1.
Jan 31, 2018 Documentation updated (developmental review)
Jan 29, 2018 Document updated. Matches package version 1.6.0.
Jan 18, 2018 Document updated. Matches package version 1.5.1.
Jan 17, 2018 Document updated. Matches package version 1.5.0.
Jan 12, 2018 Document updated. Matches package version 1.4.0.
Nov 7, 2017 Document created. Matches package version 1.0.0.