This section goes over how to get up and running quickly. We’ll assume that you have already followed the Installation instructions, and are ready to go.


It’s best to combine our documentation with the Route 53 Documentation. While we’ll do our best to make this as simple as possible, it may be necessary to look at what they’ve got for more details on behavior and how things work.

AWS credentials

Before you can make your first query to Route 53, you’ll need obtain your API credentials. Visit your security credentials page and note your Access Key ID and Secret Access Key.

Instantiate the API client

Next, you’ll want to import the module:

import route53

You can then instantiate a connection to Route53 via route53.connect():

conn = route53.connect(

You are now ready to roll. Continue reading to see how much fun there is to be had (hooray!).

Listing Hosted Zones

Let’s say you want to retrieve a representation of all of your currently existing hosted zones. These roughly correspond to domains, ala angry-squirrel.com, or python.org.

The Route53Connection.list_hosted_zones method returns a generator of HostedZone instances:

# This is a generator.
for zone in conn.list_hosted_zones():
    # You can then do various things to the zone.

    # Perhaps you want to see the record sets under this zone
    for record_set in zone.record_sets:

    # Or maybe you don't like this zone, and want to blow it away.

Creating a Hosted Zone

The Route53Connection.create_hosted_zone method creates hosted zones, and returns a tuple that contains a HostedZone instance, and some details about the pending change from the API:

new_zone, change_info = conn.create_hosted_zone(
    'some-domain.com.', comment='An optional comment.'

# You can then manipulate the HostedZone.
print("Zone ID", new_zone.id)

# This has some details about the change from the API.


Notice that we passed in a fully-qualified domain name, some-domain.com., ending in a period.

In this case, new_zone is a new HostedZone instance, and change_info is a dict with some details about the changes pending (from the Route 53 API).

Retrieving a Hosted Zone

The Route53Connection.get_hosted_zone_by_id method retrieves a specific hosted zone, by Zone ID:

zone = conn.get_hosted_zone_by_id('ZONE-ID-HERE')


A Zone ID is not the same thing as the domain name. The Zone ID is a unique string identifier for the hosted zone, as per Route 53’s records.

Deleting a Hosted Zone

Simply call the HostedZone.delete method on a HostedZone to delete it:

zone = conn.get_hosted_zone_by_id('ZONE-ID-HERE')

If you have record sets under the hosted zone, you’ll need to delete those first, or an exception will be raised. Alternatively, you can call delete() with force=True to delete the record sets and the hosted zones:


Creating a record set

Depending on which kind of record set you’d like to create, choose the appropriate create_*_record method on HostedZone. The methods return one of the ResourceRecordSet sub-classes:

new_record, change_info = zone.create_a_record(
    # Notice that this is a full-qualified name.
    # A list of IP address entries, in the case fo an A record.

# Or maybe we want a weighted round-robin set.
wrr_record1, change_info = zone.create_a_record(
wrr_record2, change_info = zone.create_a_record(

Listing record sets

In order to list record sets, use the HostedZone.record_sets property on HostedZone. Note that we don’t currently implement any convenience methods for finding record sets, so this is the way to go:

# Note that this is a fully-qualified domain name.
name_to_match = 'fuzzy.bunny.com.'
for record_set in zone.record_sets:
    if record_set.name == name_to_match:
        # Stopping early may save some additional HTTP requests,
        # since zone.record_sets is a generator.

While it may seem like extra work to craft these filters yourself, it does prevent needless additional iteration, and keeps the API more concise.

Changing a record set

Simply change one of the attributes on the various ResourceRecordSet sub-classed instances and call its save() method:

record_set.values = ['']

Deleting a record set

Similarly, delete a record set via its delete() method: