Last reviewed 7 May 2026

Applies to

Unity package manifest workflow Dependency repair Project reproducibility

Difficulty Intermediate

Creating a packages.json file

Unity package files can be confusing because two similar-sounding JSON files appear in package workflows:

• Packages/manifest.json belongs to the Unity project and lists the packages the project depends on.
• package.json belongs to an individual package and describes that package's name, version, dependencies, and metadata.

Most VRChat world builders are really looking for Packages/manifest.json when they want to repair or reproduce a project setup. You only create or edit a package's own package.json when you are making a reusable Unity package.

Which File Do You Actually Need?

The safest first step is identifying the job you are trying to do.

Goal	File to look at	Beginner advice
Check which Unity packages a project uses	Packages/manifest.json	Read it, but prefer Package Manager for normal installs and removals
Repair a missing or invalid dependency	Packages/manifest.json	Edit only the broken entry, then reopen Unity
Preserve exact resolved dependency versions	Packages/packages-lock.json	Usually commit it with the project, but do not hand-edit it casually
Make your own reusable Unity package	package.json inside that package folder	Use Unity package naming rules and test the package in a clean project
Add packages from a custom registry	Packages/manifest.json	Add both scopedRegistries and the matching dependency carefully

If a tutorial says "edit packages.json," double-check the surrounding context. Many Unity guides use that phrase loosely when they mean the project manifest at Packages/manifest.json.

What Packages/manifest.json Does

Unity's project manifest is the entry point Package Manager reads when the project opens. It tells Unity which packages to load and can also configure package sources such as scoped registries.

A simplified project manifest looks like this:

{
  "dependencies": {
    "com.unity.probuilder": "5.2.2",
    "com.unity.render-pipelines.universal": "14.0.11",
    "com.unity.textmeshpro": "3.0.6"
  }
}

The important part for most beginners is the dependencies object. Each entry has:

• a package name, such as com.unity.probuilder
• a requested version, Git URL, file path, or registry version
• JSON punctuation that must remain valid

One missing comma or quote can stop Package Manager from resolving packages correctly.

What package.json Does

A package's own package.json describes the package itself. You normally see this when building a custom Unity package, using an embedded package, or inspecting a package inside a cache or package folder.

A minimal package file can look like this:

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

That file is not the normal place to install packages into your project. It describes one package; the project manifest decides whether the project uses that package.

When Manual Editing Is Reasonable

Use Package Manager first for ordinary package installs, updates, and removals. Manual JSON edits are useful when:

• Package Manager cannot open because the project has invalid dependencies
• a tutorial gives an exact manifest entry to add
• a custom registry requires a scopedRegistries block
• you are restoring package state from a known working project
• you need to remove a broken dependency before Unity can finish loading

Manual editing is not a good place to experiment. If you are unsure which package version belongs in the file, stop and check the package documentation first.

Safe Editing Steps

Follow this process when you need to edit Packages/manifest.json:

1. Close Unity.
2. Back up the project, or commit the current state in source control.
3. Open Packages/manifest.json in a code editor.
4. Confirm the JSON is valid before changing anything.
5. Change one package entry only.
6. Save the file.
7. Reopen Unity and wait for package resolution and compiling to finish.
8. Read the first red Console error if anything fails.

Do not edit package files while several other fixes are happening at once. Package errors can look unrelated at first, so keeping the change small makes recovery much easier.

Adding A Scoped Registry

Some packages are distributed through a registry outside Unity's default registry. In that case, the project manifest needs a registry block and a dependency entry.

Example shape:

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

The scopes value tells Package Manager which package names should be searched in that registry. If the scope does not match the package name, Unity might not find the package even though the registry URL looks correct.

Common Beginner Mistakes

Editing the wrong file

If you want to install or repair packages for the current project, you usually want Packages/manifest.json, not a package's internal package.json.

Leaving invalid JSON

JSON does not allow trailing commas, missing quotes, or comments. A tiny syntax error can make the whole manifest fail.

Changing too many packages at once

If five package versions change and the project breaks, you now have five suspects. Change one important entry at a time.

Deleting packages-lock.json without a reason

packages-lock.json records resolved dependency information. Deleting it can be a troubleshooting step, but it can also cause Unity to resolve versions again. Back it up before removing it.

Mixing tutorial versions

A package entry from a Unity 2020 tutorial may not be right for a Unity 2022 or Unity 6 project. Check the Unity version before copying manifest entries.

Recovery Checklist

If Unity reports invalid dependencies after an edit:

1. Close Unity.
2. Reopen Packages/manifest.json.
3. Check for missing commas, quotes, braces, or brackets.
4. Revert the last package entry you changed.
5. If needed, restore the backed-up manifest.
6. Reopen Unity and let Package Manager resolve again.

If the project still fails, compare the manifest against a clean project made with the same Unity version. That gives you a known-good baseline without guessing.

Help! Unity says the manifest is invalid.

Close Unity, undo the last edit, and validate the JSON structure before reopening the project. Most manifest failures come from missing commas, quotes, braces, or brackets.

Help! A package is missing after I copied a project.

Check that the copied project includes its Packages folder, especially manifest.json and packages-lock.json. Then reopen Unity and let Package Manager restore dependencies.

Help! A custom registry package will not appear.

Confirm the scoped registry URL, the package name, and the scopes entry all match. If the package starts with com.example, the registry scope must cover that namespace.

Practical Advice

• Use Package Manager for routine installs and removals.
• Edit Packages/manifest.json only when you have a clear reason.
• Create a package package.json only when you are making a reusable package.
• Keep manifest edits small, reversible, and version-aware.
• For VRChat projects, confirm Creator Companion, Unity version, SDK version, and target platform before changing SDK-related dependencies.

References

• Unity Manual: Project manifest
• Unity Manual: Scoped registries

Helpful follow-up pages

• Package Manager Basics
• The project has invalid dependencies (Error)
• Unity3D Version Differences
• Unity Hub Installation

Final Advice

You do not need to memorize every package manifest option. The useful beginner skill is knowing which file controls the project, which file describes a package, and how to make one careful change without losing the ability to recover.