Where does Dart's pub store downloaded packages, and what do `dart pub cache repair`, `gc` and `clean` each do?
answer
- one system-wide cache
- ~/.pub-cache and PUB_CACHE
- never edit cached sources
- repair reinstalls
- gc drops unreferenced packages
basics
~10 sPub downloads hosted and git packages into one system-wide cache, ~/.pub-cache by default or PUB_CACHE if set. repair reinstalls cached packages, gc removes packages no current project references, and clean empties the whole cache.
solid answer
~40 sPub keeps a **system cache** shared by all projects: `~/.pub-cache` on macOS and Linux, `%LOCALAPPDATA%\Pub\Cache` on Windows, or wherever the `PUB_CACHE` environment variable points. Each version is downloaded once and reused; your project finds it through `.dart_tool/package_config.json`. Because IDEs make it easy to open cached sources, an accidental edit can break every project using that version, which is what `dart pub cache repair` fixes by reinstalling. Since Dart 3.11 it repairs only the packages in the current project's `pubspec.lock` by default, and `--all` restores the old repair-everything behaviour. `dart pub cache gc` (3.11) reclaims space by removing packages no current project references, and `dart pub cache clean` deletes the entire cache.
code
bash · 14 lines# Where is the cache? (PUB_CACHE overrides the default)
echo ${PUB_CACHE:-$HOME/.pub-cache}
# Undo an accidental edit to a cached dependency of this project
dart pub cache repair
# Repair every package in the cache
dart pub cache repair --all
# Reclaim space from packages no current project uses
dart pub cache gc
# Nuclear option: empty the whole cache
dart pub cache cleango deeper
Know that packages live in a shared ~/.pub-cache, that you never edit files there, and that repair undoes accidental edits.
Explain how package_config.json points projects into the cache and the difference between repair, gc and clean.
Use PUB_CACHE and lockfile-keyed caching in CI, and recognise corrupted-cache symptoms in builds.
Decide how build machines share and invalidate package caches so builds stay fast without hiding corrupted or stale content.
## One cache for every project When `dart pub get` needs a package from pub.dev or from Git, it downloads it into the **system package cache**, a directory shared by every Dart and Flutter project on the machine. If ten projects use `http` 1.6.0, it is downloaded and stored **once**. | Platform | Default location | |---|---| | macOS, Linux | `~/.pub-cache` | | Windows | `%LOCALAPPDATA%\Pub\Cache` (may vary by Windows version) | | Any, overridden | the directory in the `PUB_CACHE` environment variable | A project does not copy packages into itself. Instead pub writes `.dart_tool/package_config.json`, which maps each package name to its location in the cache (or to a local directory for path dependencies). That file is generated and never committed. The shared cache is also what makes **offline** resolution possible: `dart pub get --offline` resolves using only what is already cached. ## Maintenance commands The `dart pub cache` command manages the cache directly: 1. **`dart pub cache repair`** reinstalls cached packages from their sources. Use it when cached files were changed or corrupted, for example after accidentally editing a package's source opened from the IDE's "go to definition". Since **Dart 3.11** it repairs by default only the packages referenced by the current project's `pubspec.lock`; `--all` repairs every cached package, which was the older default. 2. **`dart pub cache gc`**, added in **Dart 3.11**, reclaims disk space by removing packages that **no current project references**. 3. **`dart pub cache clean`** empties the **entire** cache; the next `pub get` in each project downloads everything again. 4. **`dart pub cache add <package>`** pre-installs a package, optionally with `--version <constraint>` or `--all` matching versions. The dart.dev page for `dart pub cache` predates `gc` and still describes `repair` as reinstalling everything; the SDK changelog is the current source for both. ## Why you must not edit cached sources Cached packages are shared. A "quick fix" typed into a file under `~/.pub-cache` changes that version for **every** project on the machine, is invisible to version control, and disappears on the next repair or clean. The supported ways to patch a dependency are a fork used through a git or path dependency, or an override in the app's own pubspec. ## CI considerations - Caching the pub cache directory between CI runs, keyed on `pubspec.lock`, speeds up `dart pub get` considerably. - Setting `PUB_CACHE` inside the workspace makes that directory easy to cache and to clear. - A corrupted CI cache shows up as analyzer or compile errors inside a dependency; `repair` or clearing the cached directory fixes it. ## Disk usage over time The cache only grows as projects move to new versions. On a developer machine, `gc` is the gentle cleanup and `clean` the drastic one; either way, the next `pub get` restores exactly what each project's lockfile names.
- A developer 'fixed' a bug by editing a file inside `~/.pub-cache`. Why is that a problem, and how do you undo it?The cache is shared, so the edit silently changes that package version for every project on the machine, and no teammate or CI job has it. Run `dart pub cache repair` in an affected project to reinstall the original files, and patch properly through a fork or an override.
- How does a Dart project find packages in the pub cache without copying them?`dart pub get` writes `.dart_tool/package_config.json`, which maps each package name to its directory in the cache or to a local path. The compiler and analyzer resolve `package:` imports through that file.
saying these in an interview costs you the question
- Each project keeps its own copy of every package
- Editing files in the pub cache is a fine way to patch a dependency
- dart pub cache clean only removes unused packages
- pub cache repair always reinstalls every cached package
- The pub cache must be committed so CI can build offline