Delete Old ECR Images With a Lifecycle Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadRepositoriesAndImages",
      "Effect": "Allow",
      "Action": [
        "ecr:DescribeRepositories",
        "ecr:DescribeImages",
        "ecr:GetLifecyclePolicy"
      ],
      "Resource": "arn:aws:ecr:us-east-1:123456789012:repository/*"
    },
    {
      "Sid": "SetLifecyclePolicies",
      "Effect": "Allow",
      "Action": "ecr:PutLifecyclePolicy",
      "Resource": "arn:aws:ecr:us-east-1:123456789012:repository/*"
    }
  ]
}

// set-ecr-lifecycle-policies.ts
// Finds ECR repositories in one region without a lifecycle policy, estimates the storage an
// "untagged older than N days + keep the newest K images" policy would free, and applies that
// policy only when you pass --apply. Repositories that already have a policy are never changed.
// Usage: npx tsx set-ecr-lifecycle-policies.ts [--untagged-days 14] [--keep 30] [--apply]
import {
  ECRClient,
  paginateDescribeRepositories,
  paginateDescribeImages,
  GetLifecyclePolicyCommand,
  PutLifecyclePolicyCommand,
  LifecyclePolicyNotFoundException,
  type ImageDetail,
} from "@aws-sdk/client-ecr";

const ECR_PER_GB_MONTH = 0.1; // USD, private repository storage, us-east-1, as of September 2026

function arg(name: string): string | undefined {
  const i = process.argv.indexOf(name);
  return i === -1 ? undefined : process.argv[i + 1];
}

const ecr = new ECRClient({}); // region from AWS_REGION or your profile

function policy(untaggedDays: number, keep: number): string {
  return JSON.stringify({
    rules: [
      {
        rulePriority: 1,
        description: `Expire untagged images older than ${untaggedDays} days`,
        selection: { tagStatus: "untagged", countType: "sinceImagePushed", countUnit: "days", countNumber: untaggedDays },
        action: { type: "expire" },
      },
      {
        rulePriority: 2, // a tagStatus "any" rule must have the highest rulePriority
        description: `Keep only the newest ${keep} images`,
        selection: { tagStatus: "any", countType: "imageCountMoreThan", countNumber: keep },
        action: { type: "expire" },
      },
    ],
  });
}

async function hasPolicy(repositoryName: string): Promise<boolean> {
  try {
    await ecr.send(new GetLifecyclePolicyCommand({ repositoryName }));
    return true;
  } catch (err) {
    if (err instanceof LifecyclePolicyNotFoundException) return false;
    throw err;
  }
}

// Rough local estimate of what the policy would expire. Use the lifecycle policy preview for the exact list.
function estimate(images: ImageDetail[], untaggedDays: number, keep: number): ImageDetail[] {
  const cutoff = Date.now() - untaggedDays * 86_400_000;
  const newestFirst = [...images].sort((a, b) => (b.imagePushedAt?.getTime() ?? 0) - (a.imagePushedAt?.getTime() ?? 0));
  const isUntagged = (img: ImageDetail) => (img.imageTags ?? []).length === 0;
  const rule1 = newestFirst.filter((img) => isUntagged(img) && (img.imagePushedAt?.getTime() ?? 0) < cutoff);
  // Rule 2 counts every image but can't expire untagged ones (rule 1 has priority over them).
  const rule2 = newestFirst.slice(keep).filter((img) => !isUntagged(img));
  return [...rule1, ...rule2];
}

async function main(): Promise<void> {
  const untaggedDays = Number(arg("--untagged-days") ?? 14);
  const keep = Number(arg("--keep") ?? 30);
  const apply = process.argv.includes("--apply");

  const rows = [];
  const targets: string[] = [];
  let freeableGb = 0;
  for await (const page of paginateDescribeRepositories({ client: ecr }, {})) {
    for (const repo of page.repositories ?? []) {
      const name = repo.repositoryName ?? "";
      const images: ImageDetail[] = [];
      for await (const imgPage of paginateDescribeImages({ client: ecr }, { repositoryName: name })) {
        images.push(...(imgPage.imageDetails ?? []));
      }
      const gb = images.reduce((s, i) => s + (i.imageSizeInBytes ?? 0), 0) / 1e9;
      const untagged = images.filter((i) => (i.imageTags ?? []).length === 0).length;
      const policySet = await hasPolicy(name);
      const expiring = policySet ? [] : estimate(images, untaggedDays, keep);
      const expGb = expiring.reduce((s, i) => s + (i.imageSizeInBytes ?? 0), 0) / 1e9;
      if (!policySet) {
        targets.push(name);
        freeableGb += expGb;
      }
      rows.push({
        Repository: name,
        Images: images.length,
        Untagged: untagged,
        GB: gb.toFixed(2),
        "$/mo": (gb * ECR_PER_GB_MONTH).toFixed(2),
        "Has policy": policySet ? "yes" : "NO",
        "Would expire": policySet ? "-" : expiring.length,
        "GB freed (est.)": policySet ? "-" : expGb.toFixed(2),
      });
    }
  }

  console.table(rows);
  console.log(`${targets.length} repositories without a lifecycle policy. Estimated ${freeableGb.toFixed(2)} GB ` +
    `(about $${(freeableGb * ECR_PER_GB_MONTH).toFixed(2)}/month) would expire.`);

  if (!apply) {
    console.log("Dry run: no policy was written. Policy that --apply would set:");
    console.log(JSON.stringify(JSON.parse(policy(untaggedDays, keep)), null, 2));
    return;
  }
  for (const repositoryName of targets) {
    await ecr.send(new PutLifecyclePolicyCommand({ repositoryName, lifecyclePolicyText: policy(untaggedDays, keep) }));
    console.log(`Lifecycle policy set on ${repositoryName}`);
  }
  console.log("ECR expires matching images within 24 hours. Check CloudTrail for the deletions.");
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

npm install @aws-sdk/client-ecr
npm install --save-dev tsx typescript

# Dry run: report and print the policy it would set
AWS_PROFILE=readonly AWS_REGION=us-east-1 npx tsx set-ecr-lifecycle-policies.ts

# Keep 50 images, expire untagged after 7 days, and write the policies
AWS_PROFILE=platform-admin AWS_REGION=us-east-1 npx tsx set-ecr-lifecycle-policies.ts --untagged-days 7 --keep 50 --apply

┌─────────┬───────────────┬────────┬──────────┬─────────┬────────┬────────────┬──────────────┬─────────────────┐
│ (index) │ Repository    │ Images │ Untagged │ GB      │ $/mo   │ Has policy │ Would expire │ GB freed (est.) │
├─────────┼───────────────┼────────┼──────────┼─────────┼────────┼────────────┼──────────────┼─────────────────┤
│ 0       │ 'api'         │ 412    │ 268      │ '96.41' │ '9.64' │ 'NO'       │ 371          │ '88.02'         │
│ 1       │ 'worker'      │ 57     │ 12       │ '14.80' │ '1.48' │ 'NO'       │ 31           │ '7.95'          │
│ 2       │ 'base-images' │ 18     │ 0        │ '6.12'  │ '0.61' │ 'yes'      │ '-'          │ '-'             │
└─────────┴───────────────┴────────┴──────────┴─────────┴────────┴────────────┴──────────────┴─────────────────┘
2 repositories without a lifecycle policy. Estimated 95.97 GB (about $9.60/month) would expire.
Dry run: no policy was written. Policy that --apply would set: