Cache

ir caches resolver tooling, dependency resolutions, and materialised package libraries for runs, renders, and ad hoc package-tool runs.

Rust owns the cache root and passes it to the resolver R session as IR_CACHE_DIR. This lets warm resolution-cache hits return without launching R while keeping resolver output in the same cache tree. Installed tools use the same resolver cache for tooling and markers, but their package libraries are materialised under the durable tool store instead of IR_CACHE_DIR.

Resolution requests are keyed by declared packages, resolution source, selected R executable, and runtime selectors such as R_ARCH and R_HOME. If the same request was already resolved, ir reuses the cached library before launching the resolver R session, so pak is not invoked again. R resolution records a Unix timestamp inside the cache marker; markers older than IR_LATEST_RESOLUTION_MAX_AGE_SECONDS are refreshed in place, so changed package metadata is picked up without accumulating one marker per refresh window. The default max age is 86400 seconds (24 hours). Set IR_LATEST_RESOLUTION_MAX_AGE_SECONDS=0 to treat every time-bounded resolution marker as stale, including one written during the current second. After pak resolves the complete dependency graph, ir uses pak’s resolved source locations to choose the marker policy. Any graph containing a network-backed resolved location uses the same expiring marker policy, including registry snapshots, GitHub, GitLab, Bitbucket, git, URL, and transitive remote dependencies. An exclude-newer date remains part of the cache key, so different snapshot requests never share a marker. A mixed local/network graph follows the network policy; use --refresh to pick up local changes immediately. Python environments use separate cache markers that record the resolved Python executable path. If the recorded Python path no longer exists, ir resolves the Python environment again.

Nonempty resolution graphs with no network-backed pak source, or with any pak query modifier, skip the resolution-marker cache. Each invocation asks pak to resolve local-only graphs again, so local changes and explicit cache-control modifiers are not hidden behind a warm marker. Empty dependency graphs remain cacheable because they have no package source to invalidate.

Cache-backed materialised libraries are content-addressed by the install refs passed to renv::use(), R version, and platform. Scripts or tools that resolve to the same install refs share one library. When a source ref is re-resolved, it is passed to renv::use() so renv can refresh the source install; renv may reuse its own package cache when the source has not changed. Installed tool libraries use the same content-addressing under IR_TOOL_STORE_DIR.

Use --refresh to bypass the R and Python resolution markers for one invocation:

$ ir run --refresh --with github::r-xla/anvl -e '.libPaths()'
$ ir render --refresh report.qmd
$ rx --refresh btw --help

--refresh is available on ir run, ir render, ir preview, ir tool run, rx, and ir tool install. Set the nonempty environment variable IR_REFRESH for the same behavior. A refresh reruns dependency resolution but keeps resolver tooling, downloaded packages, uv environments, and content-addressed libraries available for reuse. The existing resolution marker is replaced only after resolution succeeds, so a failed refresh does not discard the last usable marker.

Commands

$ ir cache dir
$ ir cache clean
$ ir cache clean --force

ir cache dir prints the cache root. ir cache clean removes the whole ir cache, including resolver tooling, resolution markers, Python environment cache entries, and cache-backed materialised libraries. It does not remove installed tool libraries under IR_TOOL_STORE_DIR. --force is accepted and has the same behavior.