# hf-cache-reader
`hf-cache-reader` reads the standard Hugging Face cache layout without making
network requests. It is synchronous, read-only, and has no runtime
dependencies.
The crate understands repositories, snapshots, refs, nested files, and shared
content-addressed blobs. It does not download, modify, prune, or interpret
model files.
```rust
use hf_cache_reader::{resolve_cache_dir, scan_repo, RepoType};
fn main() -> Result<(), hf_cache_reader::Error> {
let cache_dir = resolve_cache_dir();
let scan = scan_repo(&cache_dir, RepoType::Model, "google/gemma-2-2b-it")?;
if let Some(repo) = scan.repo {
for revision in repo.revisions {
println!("{}: {} files", revision.commit_hash, revision.files.len());
}
}
Ok(())
}
```
To inventory every supported repository type in a cache:
```rust
fn main() -> Result<(), hf_cache_reader::Error> {
let cache = hf_cache_reader::scan_cache(hf_cache_reader::resolve_cache_dir())?;
println!("{} repositories", cache.repos.len());
Ok(())
}
```
## Cache location
`resolve_cache_dir()` uses this precedence:
1. `HF_HUB_CACHE`
2. `HUGGINGFACE_HUB_CACHE`
3. `$HF_HOME/hub`
4. `$XDG_CACHE_HOME/huggingface/hub`
5. `$HOME/.cache/huggingface/hub`
6. `$USERPROFILE/.cache/huggingface/hub`
7. The platform temporary directory under `huggingface/hub`
An explicit path passed to `scan_cache` or `scan_repo` is preferable when an
application already owns cache configuration.
## Layout
The reader recognizes the standard layout documented by Hugging Face:
```text
<cache>/
models--<owner>--<name>/
refs/<ref>
snapshots/<commit>/<file>
blobs/<content>
```
Dataset, Space, and Kernel repositories use the corresponding `datasets`,
`spaces`, and `kernels` prefixes.
Malformed or dangling entries below a readable cache root are reported as
`ScanWarning` values. A missing cache directory is treated as an empty cache.