> ## Documentation Index > Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt > Use this file to discover all available pages before exploring further. # Folder modes > **INFO**: > > 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, each of these modes also has a variety of behaviors, supported methods and parameters, response keys, webhook notifications, upload preset settings, and more: > **NOTE**: In fixed folder mode, renaming folders (which would in effect change the public ID of every asset under that folder and of any sub-folders), isn't supported. * In **dynamic folder** mode, assets are completely decoupled from the folders they're located in. This means that moving assets between **asset folders**, renaming folders, or even moving entire folders and their assets to a new path, DOESN'T affect the asset's **public ID** value or delivery URL path. Dynamic folder mode also provides a **display name**, which, like asset folders, can be freely modified without affecting the **public ID** and delivery URL. Dynamic folders provide Cloudinary users the flexibility to organize and manage media assets with high performance and without risk of breaking URLs in production. * In **fixed folder** mode, the folder and asset name are a direct reflection of the asset's **public ID** full path, and thus determine the delivery URL path and file name. In fixed folder mode, moving an asset to another folder or changing the asset name shown in the [Media Library](https://console.cloudinary.com/console/media_library/search), also modifies the asset's URL, and if not done carefully, risks breaking production content. > **INFO**: > > * To migrate one or more product environments to dynamic folders mode or to send questions and feedback related to dynamic folders, contact [Cloudinary support](https://support.cloudinary.com/hc/en-us/requests/new?request_subject=Dynamic%20Folders). > * 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 Assets, see [Folder modes](dam_folder_modes) in the Assets admin guide. ## Checking your product environment folder mode You can check which folder mode your product environment is using as follows: * Console: At the top of the Console UI [Dashboard](https://console.cloudinary.com/app/home/dashboard) preferences * API: Use the [config](#checking_the_folder_mode_programmatically_config_method) method of the Admin API ## Asset identifiers and folder location The following table summarizes the identifiers and folder locations available for assets in fixed and dynamic folder modes: {table:class=no-borders-med-first-column overview normal-font-fam}Identifier or Property | Description | Dynamic Folders | Fixed Folders --|--|--|-- **public\_id** Unique 1 Editable 2 | Identifies the asset in a Cloudinary delivery URL.The public ID value for images and videos shouldn't include a file extension. Include the file extension for `raw` files only.Can be up to 255 characters, including non-English characters, periods (`.`), forward slashes (`/`), underscores (`_`), hyphens (`-`).Shouldn't include any of these characters: `? & # \ % < > +`.Can't begin or end with a space or forward slash (/).1 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.2 Editable in the Media Library or programmatically, but changing it can break production code. | Displayed with less prominence in the Console UI to avoid inadvertent edits that could break links to assets in production. It may contain slashes, but they don't reflect the folder path.Components in the `public_id_prefix` can't start with 'v' followed by numeric characters, since that format is used for the version segment in delivery URLs. | Acts as the primary identifier in the Console UI, making it more prone to modifications that could potentially break 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 main name shown for the asset in the Console UI, collections and basic portals.Can be retrieved or set programmatically. Can include spaces and special characters, but not slashes (/), and can have up to 255 characters. 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 **asset\_id** Unique Not Editable | An automatically generated **immutable** asset identifier that's fully unique across all product environments and all Cloudinary accounts. Every asset saved to Cloudinary is assigned a unique asset identifier that enables you to reliably reference the asset programmatically, even if other identifier values change. | Supported | Supported **Folder Location** | The asset's location within the folder hierarchy as shown in the Console UI. | The `asset_folder` location isn't reflected in the `public_id`, even though the `public_id` may contain slashes. The `asset_folder` can be up to 255 characters, including non-English characters, periods (`.`), forward slashes (`/`), underscores (`_`), hyphens (`-`).Can't contain forward slashes (`/`). Additionally, they shouldn't include the following characters: `? & # \ % < > +`.Can't end with a space.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. | The `folder` defines both the full path of the folder where the uploaded asset will be placed and also a path value that's prepended to the public ID value with a forward slash. The folder parameter shouldn't be used in dynamic folder mode. It's officially supported for backward compatibility. See [The 'folder' parameter](#the_39_folder_39_parameter) below for more details.None of the segments of the `folder` value can start with 'v' followed by numeric characters, since that format is used for the version segment in delivery URLs. ### The 'folder' parameter The `folder` parameter of the [upload](image_upload_api_reference#upload) and [upload_presets](admin_api#upload_presets) methods is a single parameter that sets both the public ID path and the folder placement of the asset. While this parameter continues to be supported for backward compatibility for accounts that have migrated from fixed folder mode, it should not be added to new code in dynamic folder product environments. In dynamic folder mode, if necessary for your use case, you can instead set `asset_folder` and `public_id_prefix` to the same value. See below for more details on `public_id_prefix`. ### Public IDs with slashes When passing a `public_id` value that includes slashes (for example, `animals/cats/tiger`), the entire passed value is the `public_id`. * In fixed folder mode, the passed path also becomes the asset's folder path, and if the folders don't already exist, they are automatically created. * In dynamic folder mode, the path of a public ID can be useful for SEO purposes, but it has no impact on where the asset is placed. In dynamic folder mode, if you want to organize the asset into folders, make sure to also pass an `asset_folder` value. Otherwise, the asset will be located in the root folder. > **TIP**: In dynamic folder mode, if you want your public ID to include slashes, you can either pass the full path as a single string in the `public_id` parameter, or you can separately pass a `public_id_prefix` value with the path to use. The `public_id_prefix` value will be prefixed to the value specified for the public_id (or the public_id value generated based on your upload preset preferences). If you want the asset to be displayed in a folder that matches the `public_id` path, then also include an `asset_folder` parameter in your upload call with the same path. Alternatively, pass the `public_id` value without a path, and instead, specify the path in the `asset_folder` parameter, while also using the `use_asset_folder_as_public_id_prefix: true` option in your upload call or upload preset to ensure the two paths match. However, keep in mind that this only synchronizes between the `public_id` path and the **initial** `asset_folder` path. If a user later moves the asset to another asset folder, the public ID path won't change to reflect the asset's new location. This avoids changing the public ID and breaking delivery URLs in production. Additionally, when your product environment uses dynamic folder mode, your organization may find it useful to implement an asset folder structure that's completely different to your public ID paths. For example, your public ID paths might reflect names and categories of products, while your folder structure might reflect internal company groups or folders relating to steps in the production workflow, since assets can freely move between folders without affecting the delivery URLs. ### Default upload naming In both modes, if you don't manually specify a public ID, the public IDs are generated as random values. If you want descriptive public IDs for SEO purposes, then you need to define the public IDs. In dynamic folder mode, if the `display_name` is defined neither explicitly nor via the `use_filename_as_display_name` option, the initial display name will be the same as the public ID's value (or the last segment of the public ID, if the public ID includes slashes (/) ). If an upload (or upload preset) doesn't define an `asset_folder` parameter (or `folder` parameter) the asset will be uploaded to the root folder, even if the public ID includes a path with slashes. ## Upload API Product environments with dynamic folders enabled offer additional parameters. ### upload method Most parameters of the upload method are equally supported in both folder modes. The following optional parameters are available only in dynamic folder mode when using the [Upload](image_upload_api_reference#upload) API method: {table:class=no-borders overview set-first-col}Parameter | Type | Description ---|---|--- `asset_folder` | String | The folder where the asset is stored in the Console UI. This value does not impact the asset's public ID and is not case sensitive. `display_name` |String| The name that's displayed for the asset in the Console UI. This value does not impact the asset's public ID, and does not have to be unique, even within the same folder. It can have spaces and special characters, but can't include forward slashes (`/`). `public_id_prefix` |String| A string that's prepended to the `public_id` with a forward slash. The value can contain alphanumeric values and forward slashes. This prefix can be useful to provide context and improve the SEO of an asset's filename in the delivery URL, but the value does not impact the location where the asset is stored in the Console UI. `use_filename_as_display_name` |Boolean|Whether to automatically assign the filename of the uploaded asset as the asset's **display name** in the Console UI. Relevant only if `display_name` is not passed. Note that if you set this value to `true` and the original filename of the asset includes forward slashes, then the upload will fail with an error that the display name can't include slashes. > **TIP**: As with all upload parameters, you can also use these dynamic mode-specific parameters via the [upload_presets](admin_api#upload_presets) method of the Admin API or the Upload Presets UI. ### explicit method Most parameters of the explicit method are equally supported in both folder modes. The following optional parameters are available only in dynamic folder mode when using the [Explicit](image_upload_api_reference#explicit) API method: {table:class=no-borders overview set-first-col}Parameter | Type | Description ---|---|--- `asset_folder` | String | The folder where the asset will be stored in the Console UI. This enables you to move an asset from one folder to another in the Console UI. This value doesn't impact the asset's public ID. `display_name` |String| The name to display for the asset in the Console UI. This value doesn't impact the asset's public ID, and doesn't have to be unique, even within the same folder (unless `unique_display_name` is set to true via the [update](admin_api#update_details_of_an_existing_resource) method). It can have spaces and special characters, but can't include forward slashes (`/`). ### rename method The [rename](image_upload_api_reference#rename) method of the Upload API updates the asset's public_id and is supported for both dynamic and fixed folder modes. > **TIP**: The `rename` method is only for modifying the asset public ID. To change only the `display_name` for product environments using dynamic folder mode, use the `display_name` parameter of the [explicit](#explicit_method) or [update](#update_method) methods. ### Upload API responses The majority of the fields in upload API responses are identical in both modes with the following exceptions: * **Dynamic folders**: All responses that include details of an asset, include `display_name` and `asset_folder` * **Fixed folders**: All responses that include details of an asset, include `folder` ## Admin API Most endpoints and parameters of the Admin API are equally available to both modes. Product environments using dynamic folder mode have some additional endpoints available, as well as additional parameters for some of the endpoint methods. ### Checking the folder mode programmatically (Config method) If you work with multiple product environments that need to run different code depending on whether the product environment is dynamic or fixed folder mode, you can use the [config](admin_api#config) method of the Admin API to return current product environment settings, including its `folder_mode` (dynamic or fixed). For example, to return the product environment configuration including settings info: ```multi |python cloudinary.api.config(settings=True) |cli cld admin config settings=true |curl curl https://:@api.cloudinary.com/v1_1//config?settings=true ``` The response contains an object with detailed product environment information. ```json { "cloud_name": "demo", "created_at": "2023-05-08T08:20:11Z", "settings": { "folder_mode": "dynamic" }, } ``` ### resources methods The majority of the [resources](admin_api#resources) methods are identical in both modes with the following exceptions: #### by_asset_folder method The [resources by asset folder](admin_api#get_resources_by_asset_folder) method is only available in dynamic folder mode. The method returns all resources in the folder, regardless of the public ID paths of those assets. This method doesn't return assets stored in the sub-folder of the specified folder. The asset folder name isn't case sensitive. #### update method The following optional parameters are only available in dynamic folder mode when using the [Update](admin_api#update_details_of_an_existing_resource) method: {table:class=no-borders overview set-first-col}Parameter | Type | Description ---|---|--- `asset_folder` | String | The folder where the asset will be stored in the Console UI. This enables you to move an asset from one folder to another in the Console UI. This value doesn't impact the asset's public ID. `display_name` |String| The name to display for the asset in the Console UI. This value doesn't impact the asset's public ID, and doesn't have to be unique, even within the same folder (unless `unique_display_name` is set to true). It can have spaces and special characters, but can't include forward slashes (`/`). `unique_display_name`|Boolean| If `true`, and you've passed a display name that already exists within the same `asset_folder` or you specify a new `asset_folder` for the asset where the same `display_name` already exists, a random character suffix will be appended to the display name of this asset to ensure it's uniqueness within the `asset_folder`. **Default:** `false`. #### search method You can search for assets by their `asset_id` or `public_id` in both modes when using the Search method. Your search expressions can also use the following identifiers: * **Dynamic folders**: `asset_folder` and/or `display_name` * **Fixed folders**: `folder` ### upload_presets methods In dynamic folder mode, the `use_asset_folder_as_public_id_prefix` optional parameter is available in the create/update [upload_presets](admin_api#upload_presets) method of the Admin API and determines whether to automatically apply the path specified in the `asset_folder` parameter as a prefix to the `public_id` value. This ensures that the public ID path will always match the initial asset folder. As with uploading assets, the `asset_folder`, `public_id_prefix`, `use_filename_as_display_name`, as well as the `use_asset_folder_as_public_id_prefix` parameter can also be set via the [upload_presets](admin_api#upload_presets) method of the Admin API. ### upload_mappings methods When working with [upload mappings](admin_api#upload_mappings), the `folder` parameter is used in the same way for both folder modes. > **INFO**: :title=Important When using upload mappings in product environments using dynamic folder mode, the specified `folder` will be created as a new asset folder at the root level when an asset is [lazily uploaded](migration#lazy_migration_with_auto_upload) upon delivery, and will also be appended as the first segment of the public ID (like a `public_id_prefix`) for each asset that gets uploaded this way. As with any other asset folder, a folder created through this process can be renamed without breaking the public ID of the uploaded asset, but if another asset is lazily uploaded to the same upload mapping folder, the defined upload mapping parent folder will be re-created. ### folders methods The [folders](admin_api#folders) methods of the Admin API reflect the folder mode: * In fixed folder mode, the folders methods relate to public ID paths. The public ID paths of assets are the same as the folder names or path structure where those assets are stored. * In dynamic folder mode, the folders methods relate to asset folders and not to public ID paths. The public ID paths of assets are not necessarily the same as the asset folder names or path structure where those assets are located, therefore the [update_folder method](admin_api#update_folder) is only available in this mode. Make sure you don't have any code that use these methods in dynamic folder mode and then assume that the folder paths in the response relate to public ID paths. ### Admin API responses All responses in both fixed and dynamic modes that include details of assets, include the assets' `public_id` and `asset_id`. * In dynamic folder mode, the API responses include the asset's `display_name` and `asset_folder`. * In fixed folder mode, the API responses include the asset's `folder`. ## Webhook notifications Most webhook notifications are relevant for both folder modes. The following notifications are relevant only for actions in dynamic folder mode: * [resource_display_name_changed](notifications#change_display_name) * [move](notifications#move_between_asset_folders) * [move_asset_folder](notifications#move_an_asset_folder) * [delete_asset_folder](notifications#delete_an_asset_folder) ## Fetched and social media assets For both fixed and dynamic folder modes, [fetched](fetch_remote_images#fetch_and_deliver_remote_files) and [social media](social_media_profile_pictures) assets are always located in the root folder. They can't be moved to another asset folder. ## Auto-create folders The **Auto-create folders** option on the **Upload** page of the Console Settings only exists for product environments in fixed folder mode. It controls whether folders are created in the Console UI based on the public ID path and is on by default. When turned off, folders are never created in the product environment regardless of the public ID path. This option is not available and isn't relevant for product environments using dynamic folder mode.