---
tags: Documentation
---

# Manual: Asset Catalogs

Catalogs help you to organise your assets. They look a little bit like directories on disk, but they're totally independent of the location of your .blend files. Assign each asset in a .blend file to its own catalog, or have one big catalog with all the assets of all the .blend files combined. It's all up to you.

For more technical information, see [Asset Catalogs on the Blender Wiki](https://wiki.blender.org/wiki/Source/Architecture/Asset_System/Catalogs).


## The Home Location of Assets

There can be as many catalogs as you want, but **an asset can be assigned to a single catalog** at a time. This is similar to a file system, where a file is only in one directory (ignoring advanced things like symbolic links).

Catalogs themselves can be nested and moved around by dragging & dropping. Moving a catalog will not modify the assets in it; they will simply move along to the new location of the catalog.

Selecting a catalog in the asset browser will show all assets in that catalog and in child catalogs. So, in the example above, selecting `Characters/Ellie/Poses` will also show assets from `Characters/Ellie/Poses/Head` and `Characters/Ellie/Poses/Hands`.

## Assigning an Asset

To assign an action to a catalog, just drag the asset on top of the catalog.

## Components of a Catalog

Each catalog consists of a *catalog path*, a *UUID*, and a *simple name*. Normally you'd only deal with the catalog path; the rest is for internal Blender use and/or for emergency situations.

### Catalog Path

The path of a catalog determines where in the catalog hierarchy the catalog is shown. Examples are `Characters/Ellie/Poses/Hand` or `Kitbash/City/Skyscrapers`, which would result in the following catalog tree. The highlighted catalog has path `Characters/Ellie/Poses/Hand`.


### UUID

Each catalog has a UUID, which is normally hidden from the user interface (enable Developer Extras to see them). This is what is stored in the asset, and what determines the "identity" of the catalog. As a result, a catalog can be renamed or moved around (i.e. you can change its path), and all assets that are contained in it will move along with it. This only requires a change to the catalog itself, and not to any asset blend file.

### Simple Name

Each catalog has an optional *simple name*. This name is stored along with the UUID in each asset. The purpose is to make it possible for humans to recognise the catalog the asset was assigned to, even when the *catalog definition file* (see below) is lost.

Like the UUID, the simple name is normally hidden from the user interface. Enable Developer Extras in the interface preferences to make it visible in the asset browser.

## Catalog Definition Files

Asset catalogs are stored in Catalog Definition Files (CDFs). Blender 3.0 supports a single CDF per asset library. It is stored in `blender_assets.cats.txt` in the root directory of the asset library. If the file does not exist, Blender will create it when the catalogs are saved.

### Which File To Write To

Asset catalogs can be saved independently of the blend file; the catalog editor has its own "Save" button.

### Format

Catalog Definition Files (CDFs) are relatively simple text files, encoded in UTF-8. Each CDF consists of a version indicator, and a line of text per catalog. Each catalog line is colon-separated, of the form `{UUID}:{path}:{simple name}`.

### Example

This is an example of a valid catalog definition file:

# This is an Asset Catalog Definition file for Blender.
#
# Empty lines and lines starting with `#` will be ignored.
# The first non-ignored line should be the version indicator.
# Subsequent lines are of the format "CATALOG_UUID:catalog/path/for/assets:simple catalog name"

VERSION 1

313ea471-7c81-4de6-af81-fb04c3535d0e:catalog/without/simple/name:
ee9c7b60-02f1-4058-bed6-539b8d2a6d34:character/Ellie/poselib:character-Ellie-poselib
cd66bf52-58f4-45cb-a4e2-dc0e0ee8f3fe:character/Ellie/poselib:character-Ellie
4eb44ec6-3424-405b-9782-ca006953e799:character/Ellie/poselib/white space:character-Ellie-poselib-white space
b63ed357-2511-4b96-8728-1b5a7093824c:character/Ružena/poselib:Ružena pose library
dcdee4df-926e-4d72-b995-33106983bb9a:character/Ružena/poselib/face:Ružena face
fb698f2e-9e2b-4146-a539-3af292d44899:character/Ružena/poselib/hand:Ružena hands

### Valid Catalog Paths

Catalog paths follow the following rules:
* All paths are absolute; there is no difference between `/a/b` and `a/b`.
* Only `/` as separator (no `\`; think less filesystem path and more URL).
* Not empty (it's required for a valid catalog).
* No empty components (so not `a//b`; `a/b` is fine).
* Invalid characters: `:`, `\`.
* Paths are always interpreted as UTF-8.

## Future Development

:::warning
- Multiple CDFs
- Exporting in-use catalogs together with assets?
:::