Assets
Menu

Folder modes

Last updated: Oct-30-2024

Important
This page describes the ways that dynamic folder mode differs from the legacy fixed folder mode. This page is NOT RELEVANT for new Cloudinary customers that signed up after June 4th, 2024. Since that date, all new Cloudinary accounts are created using dynamic folder mode.

All Cloudinary product environments are set up to work with either dynamic folders or fixed folders. While the majority of supported Cloudinary features are identical for both modes, dynamic folders provide Cloudinary users the flexibility to organize and manage media assets with high performance and without risk of breaking URLs in production. Each mode has a variety of behaviors, settings, options and interfaces to support its unique functionality.

  • In dynamic folder mode, assets are completely decoupled from the folders they are located in. This means that moving assets between asset folders, renaming folders, or even moving entire folders and their assets to a new location is supported and does NOT affect the asset's public ID value or delivery URL.

    Dynamic folder mode also introduces the concept of a display name, which, like asset folders, can be freely modified without affecting the public ID and delivery URL.

  • In fixed folder mode, the asset's public ID (part of the delivery URL) consists of the asset name and its containing folder. Therefore, changing the asset name or moving an asset to another folder in the Media Library will modify the asset's URL, and if not done carefully, risks breaking production content.

    Note
    In fixed folder mode, renaming and moving folders (which would in effect change the public ID of every asset under that folder and of any sub-folders), is not supported.

Important
  • To migrate one or more product environments to dynamic folders mode or to send questions and feedback related to dynamic folders, contact Cloudinary support.
  • Once a product environment is migrated to dynamic folders mode, you can't revert it to fixed folders mode.
  • It's recommended that you test every element of your Cloudinary implementation on a non-production product environment before applying this mode to a production product environment.
  • To find out how folder modes impact the API, see Folder modes within the Programmable Media guide.

On this page:

Checking your product environment folder mode

You can find out if dynamic folders is enabled for your product environment by navigating to the Product Environments settings page. From the (3-dots) option menu next to the relevant product environment select Edit. Your product environment is using dynamic folder mode if the Dynamic folder mode toggle button is on. If it's off, you're using fixed folder mode.

Dynamic folders indication

Asset identifiers and folder location

The table below summarizes the identifiers for assets in fixed and dynamic folder modes, including public ID, display name, asset ID, and folder location:

Identifier or Property Description Dynamic Folders Fixed Folders
Public ID
Unique *
Editable		 Identifies the asset in a Cloudinary delivery URL.

Can include any language character (including non-English letters) as well as characters such as dots (.) dashes (-), forward slashes (/).
Can't include spaces or any of these characters: ? & # \ % < > + '.

Editable in the Media Library or programmatically, but changing it can break production code.

* Must be unique within its product environment and asset type. It's possible, though not recommended, to use the same ID for an image and a video in the same environment.

 Displayed with less prominence in the Media Library to avoid inadvertent edits that could break links to assets in production.

It may contain slashes, but they don't reflect the folder path.

 Acts as the primary identifier in the Media Library, making it more prone to modifications that could potentially break links to assets in production.

It reflects the folder location as shown in the Media Library, so moving assets risks breaking links to assets in production.
Display Name
Not Unique
Editable		 A descriptive or user-friendly name for the asset unrelated to the delivery URL path. It's the primary identifier for assets in the Media Library, collections and media portals.

Can be retrieved or set programmatically.

Can include spaces and special characters, but not slashes (/).

It's possible, though not recommended, for the same display name to be used for different assets, even in the same asset folder.

 Supported Not supported
Folder Location The asset's location within the folder hierarchy as shown in the Media Library. Not reflected in the public ID, even though the public ID may contain slashes.

Moving assets doesn't affect the asset's public ID or delivery URL, so it doesn't risk breaking links to assets in production. However, discrepancies may occur as the public ID path doesn't update to match the new folder location.

Renaming and moving asset folders is also safe and supported.

 Reflected in the public ID path.

Moving assets affects the asset's public ID and delivery URL, risking broken links to assets in production.

Renaming and moving folders is not supported.

Folder mode features

The following features differ in dynamic and fixed folder modes, or exist only in dynamic folders:

Moving assets between asset folders

Dynamic folder mode

Since dynamic asset folders are not directly tied to a physical storage location, you can move assets from one folder to another in milliseconds. Even moving thousands of assets, or very large assets has no impact on move time.

Additionally, the public ID path doesn't reflect the asset's folder location, so you can move assets freely between folders without risking breaking links to assets in production.

Fixed folder mode

Folders are directly tied to a physical storage location. As such, moving assets from one folder to another may take some time.

Moreover, since the public ID path reflects the asset's folder location, moving assets between folders risks breaking links to assets in production.

Moving and renaming asset folders (dynamic folders only)

In dynamic folder mode, moving and renaming asset folders is safe and fully supported. Use the folder right-click menu to access these options:

Note
Asset folder names are not case sensitive.

In fixed folder mode, moving and renaming folders is not supported.

Display name (dynamic folders only)

In dynamic folder mode:

  • The asset name that's shown at the top of the Media Library Preview pane and in the Summary pane of the asset management drill-down page reflects the asset's display name. Editing this value doesn't impact the asset's public ID and delivery URL.

Display name in the Media Library

  • The asset name shown in media portals and collection web pages shared via public links reflects the asset's display name, as well.

In fixed folder mode, the display name is not supported.

Public ID

You can view and edit the public ID from both the asset management drill-down page and the Preview pane. The process differs depending on whether your product environment uses dynamic folder mode or fixed folder mode. Here’s where to find the public ID in each mode:

Dynamic folder mode:

Dynamic Folder - Public ID - Manage page Asset management drill-down page Dynamic Folder - Public ID - Preview pane Preview pane

Fixed folder mode:

Fixed Folder - Public ID - Manage page Asset management drill-down page Fixed Folder - Public ID - Preview pane Preview pane

In addition to where you can view and edit public IDs in the Media Library, the public ID differs in fixed and dynamic folder modes in the following ways:

Folder path

In dynamic folder mode, the public ID field shows the entire public ID value (full path). This value isn't directly related to the Media Library folder where it's currently located. This entire value can be directly modified.

In fixed folder mode, only the asset name (the last segment of the public ID) is displayed in the Name area and is directly editable. However, if the asset is located in a folder in the Media Library, then the full public ID includes the folder path.

Editing the public ID

In dynamic folder mode, click the edit icon and modify the public ID in the dialog box that opens.

Editing a public ID in the Media Library

In fixed folder mode, click in the Name area to edit the last segment of the public ID. To change other parts of the public ID path, move the asset to the desired folder hierarchy, which updates the public ID path accordingly.

In both folder modes, to edit the public ID, users with a Media Library user role need Can edit or Can manage folder permissions for the asset's folder. In dynamic folder mode, the Show delivery URL user permission, defined in the User Management page of the Console Settings by an account admin, is also required.

Note
Depending on your setup, the Show delivery URL permission might not be available in your product environment. If it's not, Media Library users will be able to edit the public ID with only Can edit or Can manage permissions on the folder. To add this permission and control public ID editing, contact support.

Upload preset options

When uploading, you may want to consider how to name new assets and which folder to store them in. Upload presets can establish naming and storage conventions for specific types of assets, or for your entire organization.

Each folder mode provides different naming and storing methods, reflected in upload preset options. For example, dynamic folders support display names, so display name options are available in that mode. Additionally, in fixed folders, the public ID always reflects the folder you select for upload, whereas in dynamic folders, the upload preset provides a special configuration option for this to happen.

Here is the interface that shows the different naming and storing options in fixed and dynamic folder modes:

Dynamic folder mode Dynamic folder mode Fixed folder mode Fixed folder mode

Below is a summary of the naming and storing options for dynamic and fixed folder modes:

Option Dynamic Folder Mode Fixed Folder Mode
Destination folder You can optionally specify a value in the Asset folder field to determine the folder where the asset will be placed within the Media Library. The value set here doesn't impact the asset's public ID (unless you also select the Set the public ID path to match the initial asset folder path option). You can set the destination Folder in the Media Library for where all assets uploaded via this upload preset will be saved, overriding the folder that the user may have selected. The folder you set also automatically defines the URL path to prepend to the public ID of every asset uploaded using this upload preset.
Naming convention for the public ID used in delivery

If you choose the Default option, the public ID is randomly generated.1

If you choose the Custom option, you can set the public ID to match the name of the file being uploaded, with or without a randomly generated unique suffix.		 The same options are available in fixed folder mode.
URL path (public ID prefix)

If you choose the Default option, the public ID has no path (no public ID prefix).1

If you choose the Custom option, you can define the URL path (public ID prefix) to prepend to the public ID of every asset uploaded using this upload preset. You can either:

- Set the public ID path to match the initial asset folder path: Sets the public ID prefix to match the name of the asset folder the asset is initially uploaded to. If an asset is later moved to a different folder, the public ID path won't change to reflect the asset's new location.

- Prepend this path to the Public ID: Allows you to define a custom public ID prefix.

The URL path (public ID prefix) that's prepended to the public ID is determined by the Folder you select.

If an asset is later moved to a different folder, the URL path changes accordingly, which risks breaking links to assets in production.
Display name

The display name is a user-friendly name for assets that doesn't impact the delivery URL value.

By default, the asset's display name will be automatically taken from the filename of the uploaded file.1 Alternatively, you can customize the asset's display name to be the same as the public ID (without the prefix).

 Display names don't exist in fixed folder mode.
Allow or prevent overwriting existing assets

When Overwrite is enabled there are several ways to overwrite an asset:

  • Specify an exact public ID via the Advanced options in the Upload widget that matches the public ID of the asset you want to overwrite.
  • Upload to an asset folder where an existing asset has a display name that matches the name of the file being uploaded.
  • Upload a new asset with the same filename as an existing asset's public ID. To allow this way of overwriting assets, set Use filename of the uploaded file as the Public ID to on and Append a unique suffix to off.
 Overwrite works the same way in fixed folder mode, except that there's no option to overwrite assets based on display name.

Footnotes
  1. If your organization is using the Assets product only, it's usually recommended to Accept the default asset naming settings option (use the uploaded file name as the display name, but a random value for the public ID).

    If your organization uses both Assets and Programmable Media, it's recommended to consult with your developers on the preferred behavior.

Upload with existing display name (dynamic folders only)

More than one asset can have the same display name, even within the same folder. However, if you upload one or more assets using a display name that already exists, you'll be asked to decide how to proceed before uploading continues.

This situation will occur if you apply an upload preset with the Use the filename of the uploaded file as the asset's Display Name option selected (either within the Default or Custom options), and the file name of at least one of the assets you're uploading matches the display name of an existing asset or assets.

Depending on the scenario, you'll get different options to choose from:

  • If you're uploading an asset using the same display name as multiple existing assets in the same folder, you'll be asked which one of the following you want to do:

    • Keep the new and existing assets with the same name
    • Enter a different display name for the new asset being uploaded

  • If you're uploading an asset using the same display name as exactly one existing assets in the same folder, you'll be asked which one of the following you want to do:

    • Replace the existing asset with the new one being uploaded
      Note
      When a new asset replaces an existing asset (with the same display name in the same asset folder), the new asset retains the exact, existing public ID. Therefore, no public ID prefix is added to the incoming asset's public ID, even if the Set the public ID path to match the initial asset folder path or Prepend this path to the Public ID settings in the upload preset were turned on.
    • Keep the new and existing assets with the same name
    • Enter a different display name for the new asset being uploaded

  • If more than one asset that you're uploading has the same display name as existing asset in that folder, you'll be asked which one of the following you want to do:

    • Keep the new and existing assets with the same display name
    • Add a unique suffix to the display name of the new asset

    You'll be able to apply the selected behavior to all of the assets that fall into this category or to determine the naming option for each uploaded asset individually.

Media Library search

In both fixed and dynamic folder modes, global searches via the free text search box return assets matching the search value by public ID. In dynamic folders, global searches also return assets matching the search value by display name.

✔️ Feedback sent!

Rate this page: