[Spaces]: add Spaces attached volumes documentation by mishig25 · Pull Request #2377 · huggingface/hub-docs

mishig25 · 2026-04-12T20:05:46Z

Summary

Add an "Attached Volumes" section to the Spaces storage docs (docs/hub/spaces-storage.md)
Document that Spaces can mount HF repos (models, datasets, Spaces) and Storage Buckets as volumes
Describe how attached volumes appear in the Space page actions dropdown
Document access-aware filtering: private repo sources are masked for unauthorized viewers

https://moon-ci-docs.huggingface.co/docs/hub/pr_2377/en/spaces-storage

🤖 Generated with Claude Code

Note

Low Risk
Documentation-only changes describing how to attach and view volumes; no product code or behavior is modified.

Overview
Updates docs/hub/spaces-storage.md to reframe persistent storage as attached volumes, detailing how Storage Buckets mount into the Space container (RW/RO) and how volumes are shown in the Space actions dropdown.

Adds documentation for mounting models/datasets/other Spaces as read-only volumes via the huggingface_hub API, including UI behavior for private repo sources being masked for unauthorized viewers.

^{Reviewed by Cursor Bugbot for commit 13282a2. Bugbot is set up for automated code reviews on this repo. Configure here.}

Document the attached volumes feature for Spaces, including how volumes are displayed in the Space page dropdown and the access-aware filtering that masks private repository sources for unauthorized viewers. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

HuggingFaceDocBuilderDev · 2026-04-12T20:07:54Z

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

kefranabg

Nice!

Address review feedback: merge the redundant sections into a single "Attached Volumes" section and remove the separate configure note. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

kefranabg

Nice!

kefranabg · 2026-04-13T10:17:37Z

+<img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-attached-volumes-light.png"/>
+<img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-attached-volumes-dark.png"/>


Eventually we can use those screenshots to display more context but no strong opinions

Thanks a lot for using the new screenshots

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

davanstrien

Holding off on approval until clarifying API vs UI cc @kefranabg

The new section says "Spaces can mount Storage Buckets and Hugging Face repositories (models, datasets, other Spaces) as volumes", which is accurate based on the huggingface_hub API but looking at the actual Space settings UI today, I only see "Mount a bucket" — there's no UI option to mount a model, dataset, or Space as a volume IIUC?

Question for @kefranabg: is repo volume mounting intended to be exposed in the UI, or is it API-only by design? Think we can document either here but we should be careful of what we suggest is possible via UI vs huggingface_hub or API.

kefranabg · 2026-04-13T12:06:52Z

The new section says "Spaces can mount Storage Buckets and Hugging Face repositories (models, datasets, other Spaces) as volumes", which is accurate based on the huggingface_hub API but looking at the actual Space settings UI today, I only see "Mount a bucket" — there's no UI option to mount a model, dataset, or Space as a volume IIUC?

Yes currently you cannot mount a model/dataset/space via the UI. However if you've mounted a model/dataset/space via huggingface_hub API, they will appear in the UI, and you will be able to unmount them via the UI

	Hub UI	Hub API
Mount a bucket volume	yes	yes
UnMount a bucket volume	yes	yes
View a bucket volume	yes	yes
View a model/space/dataset volume	yes	yes
Mount a model/space/dataset volume	no	yes
UnMount a model/space/dataset volume	yes	yes

davanstrien · 2026-04-13T12:58:10Z

@mishig25 might be worth making clearer what is possible to do via UI/hugginface_hub? Can add some suggested wording if useful.

mishig25 · 2026-04-13T13:18:24Z

please do

Split how-to-attach into per-type bullets: buckets via UI or API, repos via huggingface_hub Python API. Add read-only rule for repo volumes. Update intro to mention repos alongside buckets. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

davanstrien · 2026-04-13T14:14:04Z

pushed some suggested wording @mishig25

Addresses julien-c review: keep the main "Attached Volumes" section focused on Storage Buckets, and move models/datasets/other Spaces into a dedicated "Mounting models, datasets, and other Spaces" section with the read-only API-only wording.

julien-c · 2026-04-14T19:43:08Z

-[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.
+[Storage Buckets](./storage-buckets) are the recommended way to persist data in your Space. Attached buckets are mounted into the Space container at the path you specify, making their contents available as local files at runtime.
+
+Buckets can be attached when creating a Space, from the Space settings UI, or programmatically via the [`huggingface_hub`](/docs/huggingface_hub/guides/manage-spaces#mount-volumes-in-your-space) Python API. They can be mounted read-write (the default) or read-only.


potentially could put a code snippet in this page as well (so agents can do it)

gary149 · 2026-04-14T19:43:16Z

~~I am an agent I want to use persistent storage with my Space - I search the web then land on this page - not super sure it's enough to understand it from my pov - how do I do this programmatically?~~

ok this works probably :)

Buckets can be attached when creating a Space, from the Space settings UI, or programmatically via the huggingface_hub Python API. They can be mounted read-write (the default) or read-only.

davanstrien · 2026-04-15T10:56:22Z

related PR here to make it easier for agents/humans to discover code examples huggingface/huggingface_hub#4108. Think that is probably sufficient vs adding more snippets here for now?

mishig25 and others added 3 commits April 13, 2026 10:49

docs: add light/dark screenshots for attached volumes

168c116

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: set width=300 for attached volumes screenshots

3b8fa5d

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: use max-width on container div instead of width on img

6061ba8

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

mishig25 changed the title ~~docs: add Spaces attached volumes documentation~~ [Spaces]: add Spaces attached volumes documentation Apr 13, 2026

mishig25 marked this pull request as ready for review April 13, 2026 09:04

mishig25 requested review from gary149 and kefranabg April 13, 2026 09:04

kefranabg reviewed Apr 13, 2026

View reviewed changes

Comment thread docs/hub/spaces-storage.md Outdated

Comment thread docs/hub/spaces-storage.md Outdated

docs: merge Storage Buckets and Attached Volumes sections

a1d9100

Address review feedback: merge the redundant sections into a single "Attached Volumes" section and remove the separate configure note. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

kefranabg approved these changes Apr 13, 2026

View reviewed changes

mishig25 mentioned this pull request Apr 13, 2026

buckets: document CopyFile operation for storage buckets #2375

Merged

mishig25 and others added 2 commits April 13, 2026 12:56

remove max-width constraint on attached volumes screenshot

2222e3d

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

set max-width 350px on attached volumes screenshot

03ccc1d

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

mishig25 requested a review from davanstrien April 13, 2026 11:06

center attached volumes screenshot with margin auto

bce9c6e

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

davanstrien requested changes Apr 13, 2026

View reviewed changes

julien-c reviewed Apr 13, 2026

View reviewed changes

Comment thread docs/hub/spaces-storage.md Outdated

julien-c reviewed Apr 13, 2026

View reviewed changes

Comment thread docs/hub/spaces-storage.md Outdated

davanstrien self-requested a review April 14, 2026 08:47

julien-c approved these changes Apr 14, 2026

View reviewed changes

julien-c reviewed Apr 14, 2026

View reviewed changes

gary149 approved these changes Apr 14, 2026

View reviewed changes

davanstrien mentioned this pull request Apr 15, 2026

docs: give manage-spaces walkthrough steps real headings huggingface/huggingface_hub#4108

Merged

3 tasks

davanstrien approved these changes Apr 15, 2026

View reviewed changes

mishig25 merged commit 950dc49 into main Apr 15, 2026
3 checks passed

mishig25 deleted the docs/spaces-attached-volumes branch April 15, 2026 12:11

		<img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-attached-volumes-light.png"/>
		<img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-attached-volumes-dark.png"/>

Conversation

mishig25 commented Apr 12, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

HuggingFaceDocBuilderDev commented Apr 12, 2026

Uh oh!

kefranabg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kefranabg left a comment

Choose a reason for hiding this comment

Uh oh!

kefranabg Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

mishig25 Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

davanstrien left a comment

Choose a reason for hiding this comment

Uh oh!

kefranabg commented Apr 13, 2026

Uh oh!

davanstrien commented Apr 13, 2026

Uh oh!

mishig25 commented Apr 13, 2026

Uh oh!

davanstrien commented Apr 13, 2026

Uh oh!

Uh oh!

Uh oh!

julien-c Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

gary149 commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davanstrien commented Apr 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

mishig25 commented Apr 12, 2026 •

edited by cursor bot

Loading

gary149 commented Apr 14, 2026 •

edited

Loading