Speed up Azure Pipelines builds with the Cache task

Useful answer

Adding a Cache@2 task to an Azure Pipelines YAML file can dramatically reduce build times by saving and reusing dependency folders such as node_modules, Maven .m2, or NuGet packages between runs. When the cache key matches, the task restores the cached content before your install step; otherwise it creates a new cache after the step finishes.

How the Cache task works

The Cache@2 task takes three main inputs:

• key – a string that uniquely identifies the cache contents. A common practice is to hash a lock file (e.g., package-lock.json or pom.xml) and include the agent OS so that caches are not shared across Windows, Linux, or macOS agents.
• path – the directory on the agent that should be cached or restored. This is usually the folder where your dependency manager stores packages.
• restoreKeys – an ordered list of fallback keys used when the primary key does not match an existing cache. This allows the pipeline to reuse a slightly older cache (e.g., ignoring a timestamp in the lock file) rather than starting from scratch.

On each run, the task first attempts to restore a cache matching any of the provided keys. If a match is found, the content is extracted to path before the next step runs. If no match exists, the step proceeds normally and, after it completes, the task saves the contents of path to a new cache entry using the primary key.

Worked example: Node.js project

The following YAML snippet shows a typical Node.js pipeline that caches the npm global folder and the project’s node_modules directory. Place this in your azure-pipelines.yml file.

# azure-pipelines.yml
trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

steps:
# 1️⃣ Restore cached npm packages
- task: Cache@2
  inputs:
    key: 'npm | "$(Agent.OS)" | package-lock.json'
    restoreKeys: |
      npm | $(Agent.OS)
    path: $(Pipeline.Workspace)/.npm

# 2️⃣ Install dependencies (uses the restored cache)
- script: npm ci
  displayName: 'Install dependencies'

# 3️⃣ Build the application
- script: npm run build
  displayName: 'Build'

# 4️⃣ (Optional) Cache the local node_modules folder after install
- task: Cache@2
  condition: succeeded()
  inputs:
    key: 'npm | "$(Agent.OS)" | package-lock.json'
    restoreKeys: |
      npm | $(Agent.OS)
    path: $(System.DefaultWorkingDirectory)/node_modules

Where to run: Edit the YAML file in your repository and push the change; Azure Pipelines will pick it up on the next run. You need permission to edit the pipeline (typically a project contributor or higher).

Explanation of placeholders:

• $(Agent.OS) resolves to the agent operating system (Windows_NT, Linux, or Darwin).
• $(Pipeline.Workspace) is a shared directory accessible to all jobs in the pipeline.
• $(System.DefaultWorkingDirectory) is the working directory for the current job.

Limits and common mistakes

Limits

• Each pipeline can store up to 10 GB of cached data across all cache entries.
• Cached entries are automatically deleted after 7 days** of inactivity.
• The Cache task does not version caches; you must manage staleness via the key.

Common mistakes

• Inaccurate key – omitting the lock file or using a variable that changes every run (e.g., a timestamp) causes a cache miss every time, eliminating any benefit.
• Caching large binaries – storing build outputs, logs, or large binary assets can quickly exceed the 10 GB limit and lead to eviction or pipeline slowdowns.
• – placing the Cache task after the dependency install step means the cache is never restored; the task only saves after the step, so you see no speed‑up.
• Forgetting to update the key – if you change package-lock.json but keep the same key, the pipeline may restore an outdated set of packages, resulting in build errors or security vulnerabilities.

How to verify caching is working

1. Check the logs – after the Cache@2 task runs, look for lines like:
1. ##[section]Starting: Cache
2. Cache hit: key matched, restoring cache
3. or Cache miss: creating new cache
2. Compare timings – note the duration of the npm ci (or equivalent) step before adding the cache and after a successful cache hit. A visible reduction indicates the cache is being used.
3. Review cache storage – navigate to Pipelines → Library → Caches (if the feature is enabled for your organization) to see the size, key, and expiration of each cache entry. Ensure the total size stays below 10 GB.

Practical check: run the pipeline twice in a row without changing any dependency files. The second run should show a Cache hit message and a shorter install step duration.

Rollback considerations

Adding a Cache task does not mutate application code or source repositories; it only writes to an external cache storage managed by Azure Pipelines. If you discover that the cache is causing issues (e.g., stale dependencies), you can simply remove or modify the Cache task in the YAML and push the change; the next pipeline run will bypass the cache. No explicit rollback procedure is required.