Version: 2021.1
Lock files
Embedded dependencies

Project manifest

When Unity loads a project, the Unity Package Manager reads the project manifest so that it can compute a list of which packages to retrieve and load. When a user installs or uninstalls a package through the Package Manager window, the Package Manager stores those changes in the project manifest file. The project manifest file manages the list of packages through the dependencies object.

In addition, the project manifest serves as a configuration file for the Package Manager, which uses the manifest to customize the registry URL and register custom registries.

You can find the project manifest file, called manifest.json, in the Packages folder under the root folder of your Unity project. Like the package manifest file, the project manifest file uses JSON (JavaScript Object Notation) syntax.

Properties

All properties are optional. However, if your project manifest file does not contain any values, the Package Manager window doesn’t load, and the Package Manager doesn’t load any packages.

Tip: At any time, you can fix any problems with your registry by choosing Reset packages to defaults from the main Unity Help menu. However, be aware that this action resets all changes you made to the dependencies of your project so it is best to do this as a last resort.

Key JSON Type Description
dependenciesIn the context of the Package Manager, a dependency is a specific package version (expressed in the form package_name@package_version) that a project or another package requires in order to work. Projects and packages use the dependencies attribute in their manifests to define the set of packages they require. For projects, these are considered direct dependencies; for packages, these are indirect, or transitive, dependencies. More info
See in Glossary
Object Collection of packages required for your project. This includes only direct dependencies (indirect dependencies are listed in package manifestsEach package has a manifest, which provides information about the package to the Package Manager. The manifest contains information such as the name of the package, its version, a description for users, dependencies on other packages (if any), and other details. More info
See in Glossary
). Each entry maps the package name to the minimum version required for the project:

{
  "dependencies": {
    "com.my-package": "2.3.1",
    "com.my-other-package": "1.0.1-preview.1",
      etc.
  }
}

Specifying a version number indicates that you want the Package Manager to download the package from the package registry (that is, the source of the package is the registry). However, in addition to using versions, you can also specify a path to a local folder or tarball file, or a Git URL.

Note: You do not need to specify embedded packages here because the Package Manager finds them inside your project’s Packages folder and loads them automatically. The Package Manager ignores any entry if there is an embedded package with the same name in its own package manifest.
enableLockFile Boolean Enables a lock file to ensure that dependencies are resolved in a deterministic manner. This is set to true by default. For more information, see Using lock files.
registry String This property is reserved for internal use only.

Note: If you want to connect to a package registry server in addition to Unity’s registry, use a scoped registry.
resolutionStrategy String Upgrades indirect dependencies based on Semantic Versioning rules. This is set to lowest by default. For more information, see Setting a resolution strategy below.
scopedRegistries Array of Objects Specify custom registries in addition to the default registry. This allows you to host your own packages.

See Scoped Registries for more details.
testables Array of Strings Lists the names of packages whose tests you want to load in the Unity Test FrameworkThe Test Framework package (formerly called the Test Runner) is a Unity tool that tests your code in both Edit mode and Play mode, and also on target platforms such as Standalone, Android, or iOS. More info
See in Glossary
. For more information, see Adding tests to a package.

Note: You do not need to specify embedded packages here because the Unity Test Framework assumes they are testable by default.
useSatSolver Boolean Enables the SAT solver-based dependency resolution algorithm. This is set to true by default.

If you set this property to false, the Package Manager uses the deprecated depth-based strategy instead.


Example

{
  "registry": "https://my.registry.com",
  "scopedRegistries": [{
    "name": "My internal registry",
    "url": "https://my.internal.registry.com",
    "scopes": [
      "com.company"
    ]
  }],
  "dependencies": {
    "com.unity.package-1": "1.0.0",
    "com.unity.package-2": "2.0.0",
    "com.company.my-package": "3.0.0",
    "com.unity.my-local-package": "file:<path>/my_package_folder",
    "com.unity.my-local-tarball": "file:<path>/my_package_tarball.tgz",
    "com.unity.my-git-package": "https://my.repository/my-package.git#v1.2.3"
  },
  "enableLockFile": true,
  "resolutionStrategy": "highestMinor",
  "testables": [ "com.unity.package-1", "com.unity.package-2" ]
}

Setting a resolution strategy

While you can add package versions explicitly to the project manifest to override Unity’s package dependency resolution in order to upgrade indirect dependencies, this is not a very good strategy, for two reasons:

  • It puts more responsibility on the project owner to maintain dependency versions.
  • Over time, you might have dependencies that are not required by the project.

A better approach is to customize how the Package Manager selects indirect dependencies based on Semantic Versioning rules by setting the resolutionStrategy property:

Value: Description:
lowest Do not upgrade indirect dependencies. Instead, it uses exactly the requested version. This is the default mode.
highestPatch Upgrade to the highest version with the same Major and Minor components. For example, with the requested version 1.2.3, this strategy selects the highest version in the range [1.2.3, 1.3.0) (that is, >= 1.2.3 and < 1.3.0).
highestMinor Upgrade to the highest version with the same Major component. For example, with the requested version 1.2.3, this strategy selects the highest version in the range [1.2.3, 2.0.0) (that is, >= 1.2.3 and < 2.0.0).

Note: Version 1.0.0 marks the first stable, production-ready version. Below that, versions 0.X.Y indicate that their API is not yet stable, and successive minor versions might introduce breaking changes. This part of the SemVer specification allows releasing early versions of a package without hampering rapid development. Because of this, when the target version is 0.X.Y, highestMinor behaves like highestPatch in order to ensure choosing a backward-compatible version. For example, with the requested version 0.1.3, this strategy selects the highest version in the range [0.1.3,0.2.0).
highest Upgrade to the highest version. For example, with the requested version 1.2.3, this strategy selects the highest version in the range [1.2.3,) (that is, >= 1.2.3 with no upper bound)

Note: These ranges never allow a dependency to jump from a stable release to a preview package.

Lock files
Embedded dependencies