Find Unused ECR Repositories

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

// find-unused-ecr-repositories.ts
// Lists every private ECR repository in a Region with its image count, stored size, last push and last
// recorded pull, and flags repositories with no push and no pull in --older-than days (default 90).
// --apply deletes the flagged repositories and all their images (force), and requires --older-than.
// Usage:
//   npx tsx find-unused-ecr-repositories.ts [--region us-east-1] [--older-than 90]
//   npx tsx find-unused-ecr-repositories.ts --region us-east-1 --older-than 180 --apply [--names repo-a,repo-b]
import {
  ECRClient,
  DeleteRepositoryCommand,
  paginateDescribeImages,
  paginateDescribeRepositories,
  type Repository,
} from "@aws-sdk/client-ecr";

const args = process.argv.slice(2);
const flag = (name: string): string | undefined => {
  const i = args.indexOf(name);
  return i >= 0 ? args[i + 1] : undefined;
};
const region = flag("--region") ?? process.env.AWS_REGION ?? "us-east-1";
const olderThanFlag = flag("--older-than");
const days = Number(olderThanFlag ?? 90);
const apply = args.includes("--apply");
const only = new Set((flag("--names") ?? "").split(",").map((n) => n.trim()).filter(Boolean));
const PRICE_PER_GB_MONTH = 0.1; // ECR storage, us-east-1, AWS Price List API, September 2026
const DAY = 86_400_000;
const ecr = new ECRClient({ region });

interface Row {
  Repository: string;
  Images: number;
  SizeGB: number;
  LastPush: string;
  LastPull: string;
  UsdPerMonth: number;
  Unused: boolean;
}

const errText = (err: unknown): string => (err instanceof Error ? `${err.name}: ${err.message}` : String(err));
const day = (d?: Date): string => (d ? d.toISOString().slice(0, 10) : "never");
const latest = (a: Date | undefined, b: Date | undefined): Date | undefined => (!a ? b : !b ? a : a > b ? a : b);

async function inspect(repo: Repository, cutoff: Date): Promise<Row> {
  const name = repo.repositoryName ?? "";
  let images = 0;
  let bytes = 0;
  let lastPush: Date | undefined;
  let lastPull: Date | undefined;
  for await (const page of paginateDescribeImages({ client: ecr }, { repositoryName: name })) {
    for (const img of page.imageDetails ?? []) {
      images++;
      bytes += img.imageSizeInBytes ?? 0;
      lastPush = latest(lastPush, img.imagePushedAt);
      lastPull = latest(lastPull, img.lastRecordedPullTime);
    }
  }
  const lastActivity = latest(latest(lastPush, lastPull), repo.createdAt);
  const sizeGB = bytes / 1024 ** 3;
  return {
    Repository: name,
    Images: images,
    SizeGB: Number(sizeGB.toFixed(2)),
    LastPush: day(lastPush),
    LastPull: day(lastPull),
    UsdPerMonth: Number((sizeGB * PRICE_PER_GB_MONTH).toFixed(2)),
    Unused: !lastActivity || lastActivity < cutoff,
  };
}

async function main(): Promise<void> {
  if (!Number.isFinite(days) || days < 1) throw new Error("--older-than must be a number of days, 1 or more");
  if (apply && !olderThanFlag) throw new Error("--apply requires an explicit --older-than, so the threshold is a deliberate choice");
  const cutoff = new Date(Date.now() - days * DAY);
  const rows: Row[] = [];
  for await (const page of paginateDescribeRepositories({ client: ecr }, {})) {
    for (const repo of page.repositories ?? []) rows.push(await inspect(repo, cutoff));
  }
  rows.sort((a, b) => Number(b.Unused) - Number(a.Unused) || b.SizeGB - a.SizeGB);
  console.table(rows);
  const unused = rows.filter((r) => r.Unused && (!only.size || only.has(r.Repository)));
  const saving = unused.reduce((sum, r) => sum + r.UsdPerMonth, 0);
  console.log(`${rows.length} repositories in ${region}; ${unused.length} with no push or pull in ${days} days, about $${saving.toFixed(2)}/month of storage.`);
  if (!apply) {
    console.log("Report only: nothing was deleted. Add --apply --older-than <days> to delete the unused repositories.");
    return;
  }
  for (const r of unused) {
    try {
      await ecr.send(new DeleteRepositoryCommand({ repositoryName: r.Repository, force: true }));
      console.log(`Deleted ${r.Repository} (${r.Images} image${r.Images === 1 ? "" : "s"}, ${r.SizeGB} GB)`);
    } catch (err) {
      console.error(`Could not delete ${r.Repository}: ${errText(err)}`);
      process.exitCode = 1;
    }
  }
}

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

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

# Report: repositories with no push or pull in 90 days
AWS_PROFILE=readonly npx tsx find-unused-ecr-repositories.ts --region us-east-1

# Delete repositories untouched for 180 days, limited to three names
AWS_PROFILE=registry-admin npx tsx find-unused-ecr-repositories.ts --region us-east-1 \
  --older-than 180 --apply --names ml/feature-builder,hackathon-2025,empty-scratch

┌─────────┬──────────────────────┬────────┬────────┬──────────────┬──────────────┬─────────────┬────────┐
│ (index) │ Repository           │ Images │ SizeGB │ LastPush     │ LastPull     │ UsdPerMonth │ Unused │
├─────────┼──────────────────────┼────────┼────────┼──────────────┼──────────────┼─────────────┼────────┤
│ 0       │ 'ml/feature-builder' │ 2      │ 12.4   │ '2026-01-11' │ '2026-01-21' │ 1.24        │ true   │
│ 1       │ 'hackathon-2025'     │ 1      │ 1.2    │ '2025-09-03' │ 'never'      │ 0.12        │ true   │
│ 2       │ 'empty-scratch'      │ 0      │ 0      │ 'never'      │ 'never'      │ 0           │ true   │
│ 3       │ 'orders-api'         │ 2      │ 0.75   │ '2026-09-26' │ '2026-09-27' │ 0.08        │ false  │
│ 4       │ 'new-service'        │ 0      │ 0      │ 'never'      │ 'never'      │ 0           │ false  │
└─────────┴──────────────────────┴────────┴────────┴──────────────┴──────────────┴─────────────┴────────┘
5 repositories in us-east-1; 3 with no push or pull in 180 days, about $1.36/month of storage.
Deleted ml/feature-builder (2 images, 12.4 GB)
Deleted hackathon-2025 (1 image, 1.2 GB)
Deleted empty-scratch (0 images, 0 GB)