HF_DATASETS_CACHE ignored?

### Describe the bug

I'm struggling to get things to respect HF_DATASETS_CACHE.

Rationale: I'm on a system that uses NFS for homedir, so downloading to NFS is expensive, slow, and wastes valuable quota compared to local disk. Instead, it seems to rely mostly on HF_HUB_CACHE.

Current version: 3.2.1dev. In the process of testing 3.4.0

### Steps to reproduce the bug

[Currently writing using datasets 3.2.1dev. Will follow up with 3.4.0 results]

dump.py:
```python
from datasets import load_dataset
dataset = load_dataset("HuggingFaceFW/fineweb", name="sample-100BT", split="train")
```

Repro steps
```bash
# ensure no cache
$ mv ~/.cache/huggingface ~/.cache/huggingface.bak

$ export HF_DATASETS_CACHE=/tmp/roller/datasets
$ rm -rf ${HF_DATASETS_CACHE}
$ env | grep HF | grep -v TOKEN
HF_DATASETS_CACHE=/tmp/roller/datasets

$ python dump.py
# (omitted for brevity)

# (while downloading) 
$ du -hcs ~/.cache/huggingface/hub
18G     hub
18G     total

# (after downloading)
$ du -hcs ~/.cache/huggingface/hub
```

It's a shame because datasets supports s3 (which I could really use right now) but hub does not.

### Expected behavior

* ~/.cache/huggingface/hub stays empty
* /tmp/roller/datasets becomes full of stuff

### Environment info

[Currently writing using datasets 3.2.1dev. Will follow up with 3.4.0 results]


FWIW, it does eventually write to /tmp/roller/datasets when generating the final version.

Hey, I’d love to work on this issue but I am a beginner, can I work it with you?

Hi @lhoestq,
I'd like to look into this issue but I'm still learning. Could you share any quick pointers on the HF_DATASETS_CACHE behavior here? Thanks!

Hi ! `HF_DATASETS_CACHE` is only for the cache files of the `datasets` library, not for the `huggingface_hub` cache for files downloaded from the Hugging Face Hub.

You should either specify `HF_HOME` (parent cache path for everything HF) or both `HF_DATASETS_CACHE` and `HF_HUB_CACHE`



Thanks for clarifying, @lhoestq! To make sure I’ve got it right:

1. **HF_DATASETS_CACHE** only controls where the **datasets** library writes its own cache files (e.g. processed shards, Arrow files, etc.).
2. Anything downloaded via **huggingface_hub** (models, tokenizers, raw files) still goes into the Hub cache (by default `~/.cache/huggingface/hub`), unless you set **HF_HUB_CACHE** or the parent **HF_HOME**.

So if you want everything off NFS and onto local disk you have two options:

- **Set both**  
  ```bash
  export HF_DATASETS_CACHE=/tmp/roller/datasets  
  export HF_HUB_CACHE=/tmp/roller/hub
  ```
- **Or set**  
  ```bash
  export HF_HOME=/tmp/roller
  ```
  which will apply to both subdirectories.

Is that correct? And would it make sense to add a note to the docs clarifying the distinction (or even support S3 for the Hub cache in the future)? I’m happy to draft a small docs PR if that would help.

Hi, yes that's correct, thanks for the clarification ! A note in the docs would be welcome, thanks

I'm downloading a HF model through vLLM, setting both HF_HUB_CACHE and HF_HOME, and still my `hub` and `xet` end up in $HOME. Anyone an idea what gives?

If you set HF_HOME you should be fine

Even HF_XET_CACHE  is placed in HF_HOME by default according to the [docs](https://huggingface.co/docs/huggingface_hub/en/package_reference/environment_variables#hfxetcache):

> **HF_XET_CACHE**
> To configure where Xet chunks (byte ranges from files managed by Xet backend) are cached locally.
> Defaults to "$HF_HOME/xet" (e.g. "~/.cache/huggingface/xet" by default).

Can you check you don't have HF_XET_CACHE or HF_HUB_CACHE that would override HF_HOME ?

Hi! Triaging older issues — this one is by design rather than a bug, and I think it can be closed.

`HF_DATASETS_CACHE` controls where the `datasets` library writes its **own** processed/cached `.arrow` shards (see `config.HF_DATASETS_CACHE`). The remote files themselves are downloaded by the `huggingface_hub` library, which has a separate cache rooted at `HF_HUB_CACHE` (defaults to `~/.cache/huggingface/hub`). They're two different caches sitting under `~/.cache/huggingface` by default, but they don't share the same env var.

For your NFS-vs-local-disk setup, the right combo is:

```bash
export HF_HOME=/tmp/roller/huggingface          # parent of both caches
# or split them:
export HF_HUB_CACHE=/tmp/roller/hub             # downloaded files
export HF_DATASETS_CACHE=/tmp/roller/datasets    # processed dataset shards
```

`HF_HUB_CACHE` (or `HF_HOME`) is what makes `~/.cache/huggingface/hub` empty in your repro.

This is briefly documented at https://huggingface.co/docs/datasets/cache and https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables — happy to send a docs PR if you think the relationship between the two should be highlighted next to `HF_DATASETS_CACHE`.

Would you mind closing this out? If you do want a follow-up doc tweak, react with 👍 here and I'll open a PR.

(Disclosure: I drafted this comment with help from Claude Code while triaging stale issues; I verified the env-var resolution against `src/datasets/config.py` on current `main`.)