Managing Cached Build Artifacts

Introduction

Becuse rixpress uses Nix as its build engine, every build artifact is cached in the Nix store (/nix/store). When you modify your pipeline, new artifacts are created, but the old ones remain. This is powerful because it allows you to access a complete history of your work. However, over time, this can lead to the Nix store consuming a significant amount of disk space.

This vignette explains how to manage this cache using the rxp_gc() function, which provides a safe and targeted way to garbage-collect old build artifacts.

Build Logs: The Key to Your Pipeline’s History

Before we discuss cleaning up, it’s important to understand how rixpress keeps track of artifacts. Every time you run rxp_make(), a detailed build log is saved in your project’s _rixpress directory. These logs record the outcome of each derivation and, crucially, the exact path to its output in the Nix store.

You can see a list of all historical builds with rxp_list_logs():

rxp_list_logs()
#>                                                         filename   modification_time size_kb
#> 1 build_log_20250815_113000_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6.rds 2025-08-15 11:30:00    0.51
#> 2 build_log_20250814_170000_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4.rds 2025-08-14 17:00:00    0.50

These logs are the foundation for debugging and retrieving historical data. For a deep dive into how to use them for troubleshooting, please see the vignette("debugging"). For now, just remember that these logs are what rxp_gc() uses to intelligently clean up your cache.

Cleaning Up Artifacts with `rxp_gc()`

The rxp_gc() function is the primary tool for managing your project’s storage footprint. It operates in two distinct modes.

1. Targeted Deletion: Cleaning Up Old Builds

The most common use case is to remove artifacts from builds that are no longer needed, while keeping recent ones. This is done by specifying the keep_since argument. The function will identify all build logs older than the given date and attempt to delete both the log files and the associated Nix store paths.

Before deleting anything, it is highly recommended to perform a dry_run. This will print a detailed report of what actions would be taken, without actually modifying your system. To avoid mistakes, this is the default behaviour of rxp_gc():

# Preview what would be deleted if we keep artifacts from August 1st, 2025 onward.
rxp_gc(keep_since = "2025-08-01", dry_run = TRUE) # dry_run = TRUE is actually the default

The output will list the log files and Nix store paths targeted for deletion. Once you have reviewed the plan and are confident, you can perform the actual cleanup by setting dry_run = FALSE.

# Keep builds from the last 30 days and delete everything older.
thirty_days_ago <- Sys.Date() - 30
rxp_gc(keep_since = thirty_days_ago)

The function will prompt you for confirmation before proceeding. It intelligently protects the artifacts from your more recent builds, so you don’t have to worry about accidentally deleting something you still need. Note that some paths may not be deleted if they are still referenced by other parts of your system (like a result symlink or an active nix-shell). rxp_gc() handles this gracefully and will report these paths as “skipped”.

2. Full Garbage Collection

If you wish to perform a complete, system-wide cleanup, you can call rxp_gc() with no arguments.

# This will trigger a full Nix garbage collection.
rxp_gc()

This is equivalent to running nix-store --gc in your terminal. It will delete all unreferenced paths from your Nix store, not just those related to your current project. This is a powerful way to reclaim a large amount of disk space, but it will remove cached artifacts for all Nix-based projects and environments on your system. Use this option when you are certain you no longer need any old, unreferenced build caches.

Conclusion

The Nix store’s caching is a powerful feature for reproducibility, but it requires occasional maintenance. rxp_gc() provides the tools you need to manage this cache effectively.