Migrating Hugging Face Repositories from the Legacy Layout to the Machine Learning Layout

As of Artifactory 7.111.1, all Hugging Face repositories that you create are created with the Machine Learning layout by default. The new Machine Learning layout is more flexible and optimized for a wide range of machine learning use cases, making it easier to scale. The new structure provides consistent behavior across all MLOps repositories and sets the foundation for offering more advanced features across all JFrog ML repositories in the future.

Migrating Your Existing Repositories

As of September 2025, even Hugging Face repositories with the legacy layout will be automatically migrated to the Machine Learning layout. To help customers adjust, JFrog is providing a self-service method, that will allow you to migrate the layout easily at your own convenience before July 2025. All Hugging Face repositories that you created prior to Artifactory version 7.111.1 can be manually migrated to the Machine Learning layout.

Note

Only a system administrator can perform this migration and other related actions.

How to Perform the Migration

Important

If you want to perform the migration on a federated repository, you must first verify the following issues before performing the migration. Otherwise, the migration can break the federated repository.

Verify that all topology members are on at least Artifactory version 7.111.x.
Replication or federation is paused.
The federation queue is empty.

Then migrate all topology instances before resuming the federation or replication.

To migrate a Hugging Face repository from the legacy layout to the Machine Learning layout:

In Artifactory, select the Administration tab and go to Repositories.
In the Repositories list, find the Hugging Face repository on which you want to perform the migration.
Go to the right end of the row of the repository and click the three dots at the end of the row. An Actions pop-up menu appears, as shown below.
In the Actions pop-up menu, click Upgrade Repository Layout. The following upgrade notice appears:
Click Upgrade in the upgrade message. After you click Upgrade, the upgrade message disappears and in the Repositories list a popup message is briefly displayed stating: "Layout convert for HuggingFace repository <repo-name> completed with result: Conversion for repo <repo-name> done."

Comparing the Old Layout vs. the New Layout

After performing the layout migration, the folder structure for the Hugging Face model changes. Prior to the migration, the Hugging Face model has a branch folder, and below that a timestamp folder. This is shown below, where main is the branch folder and 2025-04-07T07:59:29.880Z is the timestamp folder:

The Machine Learning layout combines the branch folder and the snapshot folder into one single folder, as shown below where the folder name is main_2025-04-07T07:59:29.880Z:

How to Restore the Legacy Layout

It is possible that, after performing the migration to the Machine Learning layout, you may want to revert to the legacy layout. This is performed by calling the Restore Layout API, shown below:

Usage:

curl --location 'http://<DOMAIN>/artifactory/api/artifactactions/restore_layout' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <TOKEN>' \
--data '{"repoKey":"<REPO_KEY>","packageType":"HuggingFaceML"}'

Note

packageType must always be HuggingFaceML when calling this API.

Placeholders in the API:

Placeholder	Description
`<DOMAIN>`	Your JFrog host domain.
`<TOKEN>`	The Artifactory repository token.
`<REPO_KEY>`	The repository key.

Example:

The following example demonstrates calling this API with real values for the placeholders:

curl --location 'http://my-awesome.jfrog.io/artifactory/api/artifactactions/restore_layout' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic RANDOM_TOKEN_YWRtaW46QVBBVWJjTExkZTU4WT' \
--data '{"repoKey":"hf-migrated-repo"","packageType":"HuggingFaceML"}'

When this API call is successful, a 200 success message is returned with the message: "Restore layout for HuggingFaceML repository <repository_key> completed with result: Restore layout for repo <repository_key> done."

Limitations

The process for migrating Hugging Face repositories from the legacy layout to the Machine Learning layout has the following limitation:

Limitation on the Restore Layout API: The restore capability only applies to content that was saved during the migration process. When migrating to the new layout, Artifactory generates a snapshot of your existing repositories. This means that if you migrate to the new layout and then add packages to the repository, if you choose to restore the old layout the newly added packages will be deleted and the snapshot of the old layout will be restored. So there can be data loss when restoring.