Last reviewed 31 Jul 2026

Applies to

Unity 2022.3 Unity Package Manager Custom Unity packages VRChat Creator Companion projects

Difficulty Intermediate

Understand Unity Package Manifest Files

Unity does not use a standard project file named packages.json. Similar package filenames have different owners:

• Packages/manifest.json declares the Unity packages used by a project.
• package.json describes one reusable package.
• Packages/packages-lock.json records Unity's resolved dependency graph.
• Packages/vpm-manifest.json records VPM packages in a compatible VRChat project.

Select the file by its job and location, not by a shortened filename from a tutorial.

Identify the correct file

File	Owner	What it controls	Should you edit it manually?
Packages/manifest.json	Unity project	Direct Unity Package Manager dependencies and registry configuration	Only for a documented dependency, registry setup, or targeted repair
Packages/packages-lock.json	Unity Package Manager	The successfully resolved direct and indirect dependency graph	No; treat it as generated state
<package-root>/package.json	Individual package	Package identity, version, compatibility, metadata, and package dependencies	Yes, when authoring that package
Packages/vpm-manifest.json	VPM-compatible VRChat project	Required VPM package versions	Manage through Creator Companion or the VRChat Package Resolver

The folder is part of the filename. A package.json inside a package does not replace the project's Packages/manifest.json.

Manage project dependencies

For normal Unity packages, open Window > Package Manager. Installing, updating, or removing a package there updates the project manifest for you.

For VPM packages, open the project through Creator Companion and use Manage Project. These systems can show available versions and required dependencies before applying changes.

Manual edits are appropriate when:

• Package Manager cannot load because manifest.json is malformed
• a package's official documentation provides an exact Git, local, or registry dependency
• a scoped registry must be configured
• a known working manifest needs to be restored
• you are authoring an embedded or reusable package

Back up the package files before any manual edit.

Project manifest: Packages/manifest.json

When Unity loads a project, Package Manager reads Packages/manifest.json to calculate which packages it must retrieve and load. The dependencies object lists direct dependencies.

{
  "dependencies": {
    "com.example.first-package": "1.2.3",
    "com.example.second-package": "2.0.0"
  }
}

Each entry maps a package name to a source:

Value type	Example shape	Source
Version	"1.2.3"	A package registry
Git URL	"https://example.com/repository.git#revision"	A Git repository and optional revision
Local folder	"file:../LocalPackages/example"	A folder reachable from the project
Local tarball	"file:../Packages/example.tgz"	A package archive reachable from the project

Do not add an indirect dependency to force a different version unless the package's documentation explicitly requires that direct entry. Unity's resolver normally computes indirect dependencies from the installed packages.

Lock file: Packages/packages-lock.json

After Unity computes a successful dependency resolution, it stores the result in Packages/packages-lock.json. The lock file makes subsequent resolution deterministic by preserving the selected direct and indirect package versions.

Do not hand-edit versions in the lock file. Make intentional package changes through Package Manager or the project manifest, then let Unity calculate the resulting lock state.

Preserve the project manifest and lock file together in a backup or source-control change so their states can be reviewed together.

Package manifest: package.json

A reusable Unity package has package.json at the root of that package. Unity requires:

• name, using a unique reverse-domain identifier
• version, using a semantic MAJOR.MINOR.PATCH version

Unity also recommends descriptive properties such as displayName, description, and the earliest compatible unity version.

{
  "name": "com.example.world-tools",
  "version": "1.0.0",
  "displayName": "Example World Tools",
  "description": "Editor tools for a Unity world project.",
  "unity": "2022.3"
}

This file describes the package. It does not install that package into a project. Installation is controlled by Package Manager, the project manifest, or VPM tooling.

Package dependencies

An individual package can declare its own dependencies:

{
  "name": "com.example.world-tools",
  "version": "1.0.0",
  "dependencies": {
    "com.example.shared-library": "1.1.0"
  }
}

Unity Package Manager supports specific semantic versions in a package manifest's dependencies object, not version-range syntax.

VRChat VPM manifest: Packages/vpm-manifest.json

VPM-compatible VRChat projects record their required VPM packages in Packages/vpm-manifest.json. The VRChat Package Resolver compares this manifest with the project's package folders.

If packages are missing or do not match:

1. Review the resolver prompt when Unity opens.
2. Select Show Me What's Missing to inspect the differences.
3. Use Resolve for one package or Resolve All for the versions recorded in the VPM manifest.
4. Allow package restoration and Unity importing to finish.

Creator Companion uses the same VPM library for package resolution. Use its Manage Project screen for regular package additions, updates, and removals.

VPM package package.json

A VPM-compatible package also uses Unity's package.json format, with VPM-specific additions when needed. VRChat documents fields such as:

• vpmDependencies for dependencies managed by VPM
• url for the downloadable package archive
• migration fields for legacy folders, files, or packages

These are package-authoring fields. A world or avatar creator installing a package through Creator Companion does not need to add them manually.

Configure a scoped registry

Unity supports custom registries through the project's scopedRegistries array. Each entry includes a name, registry URL, and one or more package-name scopes.

{
  "scopedRegistries": [
    {
      "name": "Example Registry",
      "url": "https://registry.example.com",
      "scopes": [
        "com.example"
      ]
    }
  ],
  "dependencies": {
    "com.example.world-tools": "1.0.0"
  }
}

Package Manager compares the package name with the configured scopes and selects the closest matching registry. Use the registry owner's exact URL, scope, and package version; placeholder values above are only the JSON shape.

Do not add a registry you do not trust. Packages can contain editor and runtime code that executes inside the Unity project.

Edit manifest.json safely

1. Close Unity.
2. Back up Packages/manifest.json and Packages/packages-lock.json, or commit them.
3. Confirm the intended package source and compatible version from its documentation.
4. Make one change in Packages/manifest.json.
5. Check the JSON punctuation and save the file.
6. Reopen Unity and wait for Package Manager to finish.
7. Check the Package Manager status bar and the first Console error.

JSON requires straight double quotes, commas between entries, and matching braces and brackets. It does not permit comments.

Verify the result

• Package Manager opens and finishes refreshing.
• The intended package appears with the expected source or version.
• No package displays a dependency error.
• The Console has no Failed to resolve packages message.
• Creator Companion still recognises the project.
• VRChat SDK panels load if the project uses the SDK.
• The manifest and lock-file changes contain only the intended package update.

A tutorial tells me to create `packages.json`.

Check the location and purpose described by the tutorial. Unity project dependencies belong in Packages/manifest.json; package metadata belongs in a package-root package.json. Do not invent a third filename.

Unity says `manifest.json` is invalid JSON.

Use the line and column in the Console error. Inspect that entry and the preceding line for a missing comma, extra comma, invalid quote, or unmatched brace, then restore the backup if the intended structure is uncertain.

A copied project is missing VRChat packages.

Keep the project's Packages configuration and the VPM Resolver. When prompted, review the missing packages and let the resolver restore the versions from vpm-manifest.json.

A scoped-registry package does not appear.

Confirm the registry URL, package name, and scope against the publisher's instructions. The scope must match the beginning of the package name closely enough for Package Manager to select that registry.

Should I edit `packages-lock.json`?

No. It records Unity's resolved graph. Change or restore the owning project or package manifest, then let Package Manager calculate the lock state.

I want to publish a package for Creator Companion.

Start with Unity's custom package structure and a valid root package.json, then follow VRChat's VPM package and repository documentation for its additional manifest fields and distribution format.

Continue learning

• Package Manager Basics
• Fix Invalid Package Dependencies in Unity
• Install and Remove Unity Add-ons Safely
• Back Up a Unity Project

Official references

• Unity 2022.3: Project manifest
• Unity 2022.3: Package manifest
• Unity 2022.3: Scoped registries
• Unity 2022.3: Lock files and dependency resolution
• VRChat Creator Companion: VPM packages
• VRChat Creator Companion: Package Resolver
• VRChat Creator Companion: Source control with VPM