Choosing a Pack UUID and Never Changing It

When a player imports a .mcpack or .mcaddon file, or when a creator drops a folder into development_behavior_packs, Minecraft Bedrock ignores the folder name and the human-readable name in the manifest once the initial scan is complete. Instead, the engine reads the UUID string inside the manifest header and uses that 36-character value as the pack's permanent primary key.

Because the display name can be changed freely or translated into dozens of languages via .lang files, the UUID is the sole anchor that binds a saved world to the packs it requires. When you apply a behavior pack to a world, the game records the header UUID and the current version array inside the world's configuration files. Every time that world opens, Minecraft searches its installed pack cache for a manifest carrying that exact header UUID.

A single behavior or resource pack actually requires at least two distinct UUIDs inside its manifest.json, and more if it uses scripts or links to a companion pack. Each UUID serves a separate tracking purpose within the engine, and mixing them up or reusing the same string twice in one file will cause the manifest parser to reject the pack immediately.

Bedrock requires standard RFC 4122 version 4 UUIDs formatted in the canonical 8-4-4-4-12 hexadecimal pattern, separated by hyphens and written in lowercase. A version 4 UUID is generated from random or pseudo-random numbers, which ensures that two creators generating IDs on different machines will never accidentally pick the same identifier.

The most common mistake new creators make is copying a manifest.json file from the official vanilla sample packs, a tutorial, or one of their own older projects and forgetting to replace the UUID strings. If you publish a pack that still carries a tutorial's UUID, any player who already has another pack installed from that same tutorial will experience a collision. Minecraft will refuse to import your pack because it believes the pack is already installed.

Never try to invent a UUID by typing random letters and numbers on your keyboard, or by taking an existing UUID and changing the last two digits. Manual modifications often include characters outside the hexadecimal range (only 0 through 9 and a through f are valid) or break the version and variant bits embedded in the third and fourth groups of the string. Always use a dedicated UUID generator tool, a code editor extension, or a built-in command-line utility (such as uuidgen on macOS and Linux, or [guid]::NewGuid() in Windows PowerShell) to produce fresh strings for every new pack and module.

{
  "format_version": 2,
  "header": {
    "name": "pack.name",
    "description": "pack.description",
    "uuid": "7b9d4e2a-1c5f-4a8b-9e3d-6f2a1b4c8d9e",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 80]
  },
  "modules": [
    {
      "type": "data",
      "uuid": "f3a1c8d4-9b2e-4f7a-8c6d-1e5b9a3f2c4d",
      "version": [1, 0, 0]
    }
  ],
  "dependencies": [
    {
      "uuid": "2e6c9a1b-4d8f-4b3e-9a7c-5d1f8e2b6a4c",
      "version": [1, 0, 0]
    }
  ]
}

Once you distribute the first version of your add-on to players, the UUIDs in your behavior pack and resource pack manifests are locked in forever. If you generate new UUIDs when releasing version 1.1.0 of your work, Minecraft will not recognize the new file as an update to version 1.0.0. Instead, the game treats it as an entirely unrelated add-on that happens to share the same display title.

For players, this creates immediate problems in existing worlds. When a player imports your updated .mcaddon file, the old version remains active in their world settings while the new version sits in the available packs list as a duplicate entry. If the player activates the new pack without removing the old one, both versions load simultaneously, causing duplicate custom items, conflicting recipes, and overlapping scripts. Even worse, if you changed any identifier namespaces alongside the UUID, or if the player removes the old pack in a way that interrupts how the world resolves its active packs, custom entities and blocks placed in the world can vanish or revert to update blocks.

Changing a header UUID also severs the link configured in the dependencies array of your companion pack. If you regenerate the resource pack's header.uuid for an update but forget to update the matching entry in the behavior pack's dependencies block, the behavior pack will fail to find its partner and refuse to load on worlds that enforce dependency checks.

{
  "format_version": 2,
  "header": {
    "name": "pack.name",
    "description": "pack.description",
    "uuid": "2e6c9a1b-4d8f-4b3e-9a7c-5d1f8e2b6a4c",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 80]
  },
  "modules": [
    {
      "type": "resources",
      "uuid": "a4d8e1f6-3c7b-4e9a-8b2d-9f1c5a7e3b6d",
      "version": [1, 0, 0]
    }
  ]
}

Instead of touching the UUIDs when you release bug fixes or new features, you signal an update to Minecraft by keeping every UUID identical and incrementing the three-number version array: [major, minor, patch]. You must increment the version array in the header block, in the modules block, and, if your companion pack requires features introduced in the new release, in the dependencies block as well.

When a player imports a .mcpack or .mcaddon whose header.uuid matches a pack already in their storage, Minecraft compares the incoming header.version against the installed version. If the incoming version is higher, the game installs the new files side-by-side in its cache and automatically upgrades worlds that use the pack (unless the world has locked its pack versions onto a specific template). During development in development_behavior_packs, where only one folder exists, bumping the version number tells active worlds that the pack definition has progressed.

Notice in the updated behavior pack manifest below that header.uuid, the data module's uuid, and the dependency uuid pointing to the resource pack are byte-for-byte identical to the version 1.0.0 manifest shown earlier. Only the version arrays have moved from [1, 0, 0] to [1, 1, 0].

{
  "format_version": 2,
  "header": {
    "name": "pack.name",
    "description": "pack.description",
    "uuid": "7b9d4e2a-1c5f-4a8b-9e3d-6f2a1b4c8d9e",
    "version": [1, 1, 0],
    "min_engine_version": [1, 20, 80]
  },
  "modules": [
    {
      "type": "data",
      "uuid": "f3a1c8d4-9b2e-4f7a-8c6d-1e5b9a3f2c4d",
      "version": [1, 1, 0]
    }
  ],
  "dependencies": [
    {
      "uuid": "2e6c9a1b-4d8f-4b3e-9a7c-5d1f8e2b6a4c",
      "version": [1, 1, 0]
    }
  ]
}

You can see firsthand why changing a UUID breaks existing saves by opening a Bedrock world folder and inspecting two small JSON files stored at the root of the save directory: world_behavior_packs.json and world_resource_packs.json. Whenever a player activates your add-on on a world, Minecraft writes an entry into these files containing only two pieces of data: the pack_id (which is your manifest's header.uuid) and the three-integer version array.

Notice that the pack's name, folder name, and module UUIDs do not appear in these world tracking files at all. When the world loads, the engine reads each pack_id in the list and asks the pack manager for that exact UUID. If you shipped an update with a brand-new UUID and the player deleted the older version of your pack from their global storage cache, the world loader hits a dead end: it finds an entry in world_behavior_packs.json pointing to a UUID that no longer exists on the device, and throws a missing pack warning before loading the world without your add-on.

[
  {
    "pack_id": "7b9d4e2a-1c5f-4a8b-9e3d-6f2a1b4c8d9e",
    "version": [1, 1, 0]
  }
]

There are only three situations where generating new UUIDs is the right move. The first is when you start a brand-new add-on project by duplicating an existing pack folder as a starter template. Before you write a single line of block, entity, or item code, your very first step must be replacing every header and module UUID in both the behavior and resource pack manifests so your new project does not overwrite or collide with the project you copied it from.

The second situation is when you add a new module to an existing pack—for example, adding a script module alongside your existing data module in a behavior pack. The new script module object in the modules array needs its own freshly generated UUID, while the existing header.uuid and data module uuid remain completely untouched.

The third is when you intentionally fork an add-on into a standalone edition (such as a 'Lite' version or a sequel pack) that players should be able to install and activate alongside the original pack in the same world without one replacing the other. If both editions are meant to coexist on the same device as separate entries in the pack list, they must have distinct UUIDs and distinct content namespaces.

Applies to all versions of Minecraft Bedrock Edition using manifest format_version 1 and 2. No experimental toggles are required.

Read out of the game itself, so the ids match the version you are building for.