huggingface · Pierrci · Apr 8, 2026 · Apr 3, 2026 · Apr 3, 2026
diff --git a/docs/hub/_toctree.yml b/docs/hub/_toctree.yml
@@ -332,7 +332,7 @@
   - local: spaces-dev-mode
     title: Spaces Dev Mode
   - local: spaces-storage
-    title: Spaces Persistent Storage
+    title: Spaces Disk Usage & Storage
   - local: spaces-custom-domain
     title: Spaces Custom Domain
   - local: spaces-mcp-servers

diff --git a/docs/hub/spaces-oauth.md b/docs/hub/spaces-oauth.md
@@ -2,7 +2,7 @@
 
 You can enable a built-in sign-in flow in your Space by seamlessly creating and associating an [OAuth/OpenID connect](https://developer.okta.com/blog/2019/10/21/illustrated-guide-to-oauth-and-oidc) app so users can log in with their HF account.
 
-This enables new use cases for your Space. For instance, when combined with [Persistent Storage](https://huggingface.co/docs/hub/spaces-storage), a generative AI Space could allow users to log in to access their previous generations, only accessible to them.
+This enables new use cases for your Space. For instance, when combined with [Storage Buckets](https://huggingface.co/docs/hub/storage-buckets), a generative AI Space could allow users to log in to access their previous generations, only accessible to them.
 
 > [!TIP]
 > This guide will take you through the process of integrating a *Sign-In with HF* button into any Space. If you're seeking a fast and simple method to implement this in a **Gradio** Space, take a look at its [built-in integration](https://www.gradio.app/guides/sharing-your-app#o-auth-login-via-hugging-face).

diff --git a/docs/hub/spaces-overview.md b/docs/hub/spaces-overview.md
@@ -68,7 +68,7 @@ Note: Find more detailed and comprehensive pricing information on [our pricing p
 
 Do you have an awesome Space but need help covering the hardware upgrade costs? We love helping out those with an innovative Space so please feel free to apply for a community GPU grant using the link in the _Settings_ tab of your Space and see if yours makes the cut!
 
-Read more in our dedicated sections on [Spaces GPU Upgrades](./spaces-gpus) and [Spaces Storage Upgrades](./spaces-storage).
+Read more in our dedicated sections on [Spaces GPU Upgrades](./spaces-gpus) and [Spaces Disk Usage & Storage](./spaces-storage).
 
 <div class="flex justify-center">
 <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-gpu-settings.png"/>
@@ -114,7 +114,7 @@ If you want to duplicate a Space, you can click the three dots at the top right
 * Space name
 * Visibility: The Space is private by default. Read more about visibility options [here](./repositories-settings#repository-visibility).
 * Hardware: You can choose the hardware on which the Space will be running. Read more about hardware upgrades [here](./spaces-gpus).
-* Storage: If the original repo uses persistent storage, you will be prompted to choose a storage tier. Read more about persistent storage [here](./spaces-storage).
+* Storage: If the original repo uses a storage bucket, you will be prompted to configure storage. Read more about disk usage and storage [here](./spaces-storage).
 * Secrets and variables: If the original repo has set some secrets and variables, you'll be able to set them while duplicating the repo.
 
 Some Spaces might have environment variables that you may need to set up. In these cases, the duplicate workflow will auto-populate the public Variables from the source Space, and give you a warning about setting up the Secrets. The duplicated Space will use a free CPU hardware by default, but you can later upgrade if needed.

diff --git a/docs/hub/spaces-sdks-docker-giskard.md b/docs/hub/spaces-sdks-docker-giskard.md
@@ -34,7 +34,7 @@ You can deploy Giskard on Spaces with just a few clicks:
 > [!WARNING]
 > IMPORTANT NOTE ABOUT DATA PERSISTENCE:
 > You can use the Giskard Space as is for initial exploration and experimentation. For **longer use in 
-> small-scale projects, activate the [paid persistent storage option](https://huggingface.co/docs/hub/spaces-storage)**. This prevents data loss during Space restarts which 
+> small-scale projects, attach a [Storage Bucket](https://huggingface.co/docs/hub/storage-buckets)**. This prevents data loss during Space restarts which 
 > occur every 24 hours.
 
 You need to define the **Owner** (your personal account or an organization), a **Space name**, and the **Visibility**. 

diff --git a/docs/hub/spaces-sdks-docker-jupyter.md b/docs/hub/spaces-sdks-docker-jupyter.md
@@ -28,14 +28,10 @@ Spaces requires you to define:
 
 <Tip warning={true}}>
 
-Storage in Hugging Face Spaces is ephemeral, and the data you store in the default configuration can be lost in a reboot or reset of the Space. We recommend to save your work to a remote location or to use persistent storage for your data.
+Storage in Hugging Face Spaces is ephemeral, and the data you store in the default configuration can be lost in a reboot or reset of the Space. We recommend saving your work to a remote location or attaching a [Storage Bucket](https://huggingface.co/docs/hub/storage-buckets) to your Space for persistent data.
 
 </Tip>
 
-### Setting up persistent storage
-
-To set up persistent storage on the Space, you go to the Settings page of your Space and choose one of the options: `small`, `medium` and `large`. Once persistent storage is set up, the JupyterLab image gets mounted in `/data`.
-
 
 ## Read more
 

diff --git a/docs/hub/spaces-sdks-docker-langfuse.md b/docs/hub/spaces-sdks-docker-langfuse.md
@@ -34,7 +34,7 @@ To get started, click the button above or follow these steps:
 1. Create a [**new Hugging Face Space**](https://huggingface.co/new-space)
 2. Select **Docker** as the Space SDK
 3. Select **Langfuse** as the Space template
-4. Enable **persistent storage** to ensure your Langfuse data is persisted across restarts
+4. Attach a **[Storage Bucket](https://huggingface.co/docs/hub/storage-buckets)** to ensure your Langfuse data is persisted across restarts
 5. Ensure the space is set to **public** visibility so Langfuse API/SDK's can access the app (see note below for more details)
 6. [Optional but recommended] For a secure deployment, replace the default values of the **environment variables**:
    - `NEXTAUTH_SECRET`: Used to validate login session cookies, generate secret with at least 256 entropy using `openssl rand -base64 32`.

diff --git a/docs/hub/spaces-sdks-docker.md b/docs/hub/spaces-sdks-docker.md
@@ -131,9 +131,7 @@ COPY --chown=user checkpoint .
 
 ## Data Persistence
 
-The data written on disk is lost whenever your Docker Space restarts, unless you opt-in for a [persistent storage](./spaces-storage) upgrade.
-
-If you opt-in for a persistent storage upgrade, you can use the `/data` directory to store data. This directory is mounted on a persistent volume, which means that the data written in this directory will be persisted across restarts.
+The data written on disk is lost whenever your Docker Space restarts. To persist data across restarts, you can attach a [Storage Bucket](./storage-buckets) to your Space.
 
 <Tip warning="{true}">
 

diff --git a/docs/hub/spaces-storage.md b/docs/hub/spaces-storage.md
@@ -1,60 +1,15 @@
 # Disk usage on Spaces
 
 Every Space comes with a small amount of disk storage. This disk space is ephemeral, meaning its content will be lost if your Space restarts or is stopped.
-If you need to persist data with a longer lifetime than the Space itself, you can:
-- [Use a dataset as a data store](#dataset-storage)
+If you need to persist data with a longer lifetime than the Space itself, you can attach one (or more) Storage Buckets.
 
-## Persistent storage
-
-> [!NOTE]
-> The persistent storage feature is no longer available.
-
-You can upgrade your Space to have access to persistent disk space from the **Settings** tab.
+## Storage Buckets
 
+[Storage Buckets](./storage-buckets) are the recommended way to persist data in your Space. You can attach a bucket when creating a Space or from the Space settings later. The bucket is mounted into your Space and can be used to store files that persist across restarts.
 
 <div class="flex justify-center">
-<img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-storage-settings.png"/>
-<img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-storage-settings-dark.png"/>
+<img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-attach-bucket.png"/>
+<img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-attach-bucket-dark.png"/>
 </div>
 
-You can choose the storage tier of your choice to access disk space that persists across restarts of your Space.
-
-Persistent storage acts like traditional disk storage mounted on `/data`.
-
-That means you can `read` and `write to` this storage from your Space as you would with a traditional hard drive or SSD.
-
-Persistent disk space can be upgraded to a larger tier at will, though it cannot be downgraded to a smaller tier. If you wish to use a smaller persistent storage tier, you must delete your current (larger) storage first.
-
-If you are using Hugging Face open source libraries, you can make your Space restart faster by setting the environment variable `HF_HOME` to `/data/.huggingface`. Libraries like `transformers`, `diffusers`, `datasets` and others use that environment variable to cache any assets downloaded from the Hugging Face Hub. Setting this variable to the persistent storage path will make sure that cached resources do not need to be re-downloaded when the Space is restarted. 
-
-> [!WARNING]
-> WARNING: all data stored in the storage is lost when you delete it.
-
-### Persistent storage specs
-
-Here are the specifications for each of the different upgrade options:
-
-| **Tier**        	| **Disk space** 	| **Persistent** 	| **Monthly Price** 	|
-|------------------	|------------------	|------------------	|----------------------	|
-| Free tier        	| 50GB            	| No (ephemeral)  	| Free!                	|
-| Small           	| 20GB             	| Yes           	| $5                	|
-| Medium         	| 150 GB           	| Yes           	| $25                	|
-| Large         	| 1TB              	| Yes           	| $100                	|
-
-
-### Billing
-
-Billing of Spaces is based on hardware usage and is computed by the minute: you get charged for every minute the Space runs on the requested hardware, regardless of whether the Space is used.
-
-Persistent storage upgrades are billed until deleted, even when the Space is not running and regardless of Space status or running state.
-
-Additional information about billing can be found in the [dedicated Hub-wide section](./billing).
-
-## Dataset storage
-
-If you need to persist data that lives longer than your Space, you could use a [dataset repo](./datasets).
-
-You can find an example of persistence [here](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver), which uses the [`huggingface_hub` library](https://huggingface.co/docs/huggingface_hub/index) for programmatically uploading files to a dataset repository. This Space example along with [this guide](https://huggingface.co/docs/huggingface_hub/main/en/guides/upload#scheduled-uploads) will help you define which solution fits best your data type.
-
-Visit the [`datasets` library](https://huggingface.co/docs/datasets/index) documentation and the [`huggingface_hub` client library](https://huggingface.co/docs/huggingface_hub/index) 
-documentation for more information on how to programmatically interact with dataset repos.
+See the [Storage Buckets documentation](./storage-buckets) for full details on creating and using buckets.
diff --git a/docs/hub/spaces.md b/docs/hub/spaces.md
@@ -18,7 +18,7 @@ You'll also be able to upgrade your Space to run [on a GPU or other accelerated
   - [How to Add a Space to ArXiv](./spaces-add-to-arxiv)
 - [Spaces Dev Mode](./spaces-dev-mode)
 - [Spaces GPU Upgrades](./spaces-gpus)
-- [Spaces Persistent Storage](./spaces-storage)
+- [Spaces Disk Usage & Storage](./spaces-storage)
 - [Gradio Spaces](./spaces-sdks-gradio)
 - [Docker Spaces](./spaces-sdks-docker)
 - [Static HTML Spaces](./spaces-sdks-static)