aws-cidr-finder master PyPI codecov


aws-cidr-finder is a Python CLI tool which finds unused CIDR blocks (IPv4 only currently) in your
AWS VPCs and outputs them to STDOUT. It is very simple, but can be quite useful for users who manage
many subnets across one or more VPCs.

Use aws-cidr-finder -h to see command options.

An Example

It is easiest to see the value of this tool through an example. Pretend that we have the following
VPC setup in AWS:

  • A VPC whose CIDR is, with a Name tag of Hello World
  • Six subnets in that VPC whose CIDRs are:

aws-cidr-finder allows you to quickly compute the CIDRs that you still have available in the VPC
without having to do a lot of annoying/tedious octet math. If we issue this command:

aws-cidr-finder --profile myprofile

We should see this output:

Here are the available CIDR blocks in the 'Hello World' VPC:
CIDR               IP Count
---------------  ----------         8192       32768
Total                 40960

You should notice that by default, aws-cidr-finder will automatically “simplify” the CIDRs
by merging adjacent free CIDR blocks so that the resulting table shows the maximum contiguous space
per CIDR (in other words, the resulting table has the fewest number of rows possible). This is why
the result of the command displayed only two CIDRs: a /19 and a /17.

Note that the first CIDR is /19 instead of, for example, /18, because the /18 CIDR would
mathematically have to begin at IP address, and that IP address is already taken by a

However, we can change this “simplification” behavior by specifying the --mask CLI flag:

aws-cidr-finder --profile myprofile --mask 20

Now, the expected output should look something like this:

Here are the available CIDR blocks in the 'Hello World' VPC:
CIDR               IP Count
---------------  ----------         4096        4096        4096        4096        4096        4096        4096        4096        4096        4096
Total                 40960

With the --mask argument, we can now query our available network space to our desired level of
detail, as long as we do not specify a smaller mask than the largest mask in the original list. For

$ aws-cidr-finder --profile myprofile --mask 18
Desired mask (18) is incompatible with the available CIDR blocks!
Encountered a CIDR whose mask is 19, which is higher than 18. Offending CIDR:
Run the command again without the --masks argument to see the full list.


If you have Python >=3.10 and <4.0 installed, aws-cidr-finder can be installed from PyPI using
something like

pip install aws-cidr-finder


All that needs to be configured in order to use this CLI is an AWS profile or keypair. The former
may be specified using the --profile argument on the CLI, while the keypair must be specified in
environment variables. If both are available simultaneously, aws-cidr-finder will prefer the

The environment variables for the keypair approach are AWS_ACCESS_KEY_ID and

You should also ensure that the profile/keypair you are using has the AWS IAM access needed to make
the underlying API calls via Boto. Here is a minimal IAM policy document that fills this

  "Effect": "Allow",
  "Action": [
  "Resource": "*"

Read more about the actions shown above


See for developer-oriented information.


View Github