Find and Release Unassociated Elastic IP Addresses

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReportElasticIps",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeAddresses",
        "ec2:DescribeRegions"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ReleaseElasticIps",
      "Effect": "Allow",
      "Action": "ec2:ReleaseAddress",
      "Resource": "arn:aws:ec2:*:*:elastic-ip/*"
    }
  ]
}

// release-unassociated-eips.ts
// Lists Elastic IP addresses that aren't associated with anything and, only when
// you pass --release, releases them. The default run is a report and changes nothing.
import {
  EC2Client,
  DescribeAddressesCommand,
  DescribeRegionsCommand,
  ReleaseAddressCommand,
  type Address,
} from "@aws-sdk/client-ec2";

// Public IPv4 price from the Amazon VPC pricing page, as of September 2026.
const PRICE_PER_IP_HOUR = 0.005;
const HOURS_PER_MONTH = 720; // 30 days, as in the AWS pricing examples

const args = process.argv.slice(2);
const RELEASE = args.includes("--release");
const ALL_REGIONS = args.includes("--all-regions");
const KEEP_TAG = "keep"; // tag an address keep=true to protect it
const HOME_REGION = process.env.AWS_REGION ?? "us-east-1";

type Row = { region: string; publicIp: string; allocationId: string; name: string; action: string };

function tag(address: Address, key: string): string | undefined {
  return address.Tags?.find((t) => t.Key?.toLowerCase() === key)?.Value;
}

// Why an address must not be released, or undefined when it is safe to release.
function skipReason(a: Address): string | undefined {
  if (a.AssociationId || a.InstanceId || a.NetworkInterfaceId) return "associated";
  if (a.ServiceManaged) return `managed by ${a.ServiceManaged}`;
  if (a.CustomerOwnedIp || a.CarrierIp) return "customer-owned or carrier IP";
  if (!a.AllocationId) return "no allocation ID";
  if (tag(a, KEEP_TAG)?.toLowerCase() === "true") return "tagged keep=true";
  return undefined;
}

async function regionsToScan(): Promise<string[]> {
  if (!ALL_REGIONS) return [HOME_REGION];
  const ec2 = new EC2Client({ region: HOME_REGION });
  const res = await ec2.send(new DescribeRegionsCommand({})); // enabled regions only
  return (res.Regions ?? []).map((r) => r.RegionName).filter((r): r is string => !!r);
}

async function scanRegion(region: string): Promise<Row[]> {
  const ec2 = new EC2Client({ region });
  // DescribeAddresses returns every Elastic IP in the region in one response.
  const { Addresses = [] } = await ec2.send(new DescribeAddressesCommand({}));
  const rows: Row[] = [];

  for (const a of Addresses) {
    const reason = skipReason(a);
    if (reason === "associated") continue; // in use: never touched, not listed
    const row: Row = {
      region,
      publicIp: a.PublicIp ?? "-",
      allocationId: a.AllocationId ?? "-",
      name: tag(a, "name") ?? "",
      action: reason ? `skipped (${reason})` : RELEASE ? "released" : "would release",
    };
    if (!reason && RELEASE) {
      try {
        await ec2.send(
          new ReleaseAddressCommand({
            AllocationId: a.AllocationId,
            NetworkBorderGroup: a.NetworkBorderGroup,
          }),
        );
      } catch (err) {
        row.action = `failed: ${(err as Error).name}`;
      }
    }
    rows.push(row);
  }
  return rows;
}

async function main(): Promise<void> {
  const rows: Row[] = [];
  for (const region of await regionsToScan()) rows.push(...(await scanRegion(region)));

  if (rows.length === 0) {
    console.log("No unassociated Elastic IP addresses found.");
    return;
  }
  console.table(rows);

  const idle = rows.filter((r) => !r.action.startsWith("skipped")).length;
  const monthly = idle * PRICE_PER_IP_HOUR * HOURS_PER_MONTH;
  console.log(`${idle} releasable address(es), about $${monthly.toFixed(2)} per 30 days at $${PRICE_PER_IP_HOUR}/hour.`);
  if (!RELEASE && idle > 0) console.log("Dry run: nothing was released. Re-run with --release to release them.");
}

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

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

# Report only, current region (the default: nothing is released)
AWS_PROFILE=readonly AWS_REGION=us-east-1 npx tsx release-unassociated-eips.ts

# Report across every enabled region
AWS_PROFILE=readonly npx tsx release-unassociated-eips.ts --all-regions

# Release after you have reviewed the report
AWS_PROFILE=admin npx tsx release-unassociated-eips.ts --all-regions --release

┌─────────┬─────────────┬───────────────┬──────────────────────────────┬───────────────┬──────────────────────────────┐
│ (index) │ region      │ publicIp      │ allocationId                 │ name          │ action                       │
├─────────┼─────────────┼───────────────┼──────────────────────────────┼───────────────┼──────────────────────────────┤
│ 0       │ 'us-east-1' │ '3.214.10.21' │ 'eipalloc-0a1b2c3d4e5f6a7b8' │ 'old-bastion' │ 'would release'              │
│ 1       │ 'us-east-1' │ '52.4.188.90' │ 'eipalloc-0f9e8d7c6b5a49382' │ 'partner-vpn' │ 'skipped (tagged keep=true)' │
│ 2       │ 'eu-west-1' │ '34.240.77.3' │ 'eipalloc-01234abcd5678ef90' │ ''            │ 'would release'              │
└─────────┴─────────────┴───────────────┴──────────────────────────────┴───────────────┴──────────────────────────────┘
2 releasable address(es), about $7.20 per 30 days at $0.005/hour.
Dry run: nothing was released. Re-run with --release to release them.