Install & Compatibility
Where this runs
tested against v5.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 78.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.0s · import 0.000s · 79MB
78MB installed
● package 78MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
certbot-dns-route53
✓ This is primarily a Certbot plugin used via the command line and typically not imported directly in Python code for its core functionality.
The plugin integrates with Certbot's command-line interface to perform DNS challenges, rather than offering a public Python API for direct application integration.
This quickstart demonstrates how to use `certbot-dns-route53` to obtain a wildcard certificate. It highlights the requirement to set AWS credentials via environment variables (or other `boto3` supported methods) and the basic `certbot` command line usage with the `--dns-route53` authenticator.
import os
# Set AWS credentials as environment variables. For production, consider IAM roles or ~/.aws/credentials.
# Ensure the IAM user/role has the necessary Route 53 permissions (see warnings).
os.environ['AWS_ACCESS_KEY_ID'] = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_AWS_ACCESS_KEY_ID')
os.environ['AWS_SECRET_ACCESS_KEY'] = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_AWS_SECRET_ACCESS_KEY')
# Example command to obtain a certificate for a domain and its wildcard using dns-route53 authenticator
# Replace example.com with your domain.
# For actual use, remove --dry-run to issue a real certificate.
# If running in a CI/CD pipeline, consider --non-interactive and --agree-tos.
print("Run this command in your terminal:")
print(f"certbot certonly --dns-route53 -d example.com -d *.example.com --email user@example.com --agree-tos --non-interactive --dry-run")
# To verify plugin availability, you can run:
# certbot plugins
certbot --version
Debug
Known issues
breakingWhen upgrading Certbot to major versions (e.g., 5.x.x), underlying changes in Certbot's core or its dependencies might affect plugins. While `certbot-dns-route53` itself often remains stable at the plugin level, ensure your Certbot installation is compatible and update the plugin simultaneously. Specifically, Certbot 5.0.0 removed pyopenssl x509 and PKey objects, which could affect advanced programmatic interactions if you were relying on internal Certbot APIs.fixAlways update `certbot` and `certbot-dns-route53` together. Review Certbot's release notes for breaking changes, especially those related to plugin integration or internal API usage.
affects: 5.0.0 and newer (Certbot core)
gotchaIncorrect AWS IAM Permissions: The AWS IAM user or role used by `certbot-dns-route53` must have specific permissions for Route 53. If these permissions are too restrictive or missing, Certbot will fail to create/delete DNS records, leading to authentication failures.fixEnsure the IAM policy includes at least: `route53:ListHostedZones`, `route53:GetChange`, and `route53:ChangeResourceRecordSets`. For `ChangeResourceRecordSets`, it's recommended to restrict the `Resource` to specific hosted zones (`arn:aws:route53:::hostedzone/YOURHOSTEDZONEID`) for least privilege.
affects: All versions
gotchaAWS Credentials Not Found (especially with `sudo`): When running `certbot` with `sudo`, it looks for AWS credentials in the `/root/` directory or environment variables for the root user. If your credentials (`~/.aws/credentials` or environment variables) are configured for your non-root user, Certbot will report that it's 'Unable to locate credentials'.fixAvoid using `sudo` if possible by configuring Certbot's directories to be writable by your user. If `sudo` is necessary, ensure AWS credentials are either set as environment variables for the root user or present in `/root/.aws/credentials`. Alternatively, use IAM roles if running on an EC2 instance.
affects: All versions
gotchaDuplicate TXT Record Error for Apex + Wildcard Domains: When requesting a certificate for both an apex domain (e.g., `example.com`) and its wildcard (e.g., `*.example.com`), Certbot might attempt to create the same `_acme-challenge` TXT record twice. Route 53 rejects duplicate TXT values within a record set, leading to a `botocore.errorfactory.InvalidChangeBatch: Duplicate Resource Record` error.fixThis is an upstream issue (Certbot #10593). Monitor Certbot releases for a fix. A potential workaround might involve requesting the apex and wildcard certificates separately if you encounter this, or manually cleaning up the TXT record between challenge attempts if using manual mode for debugging.
affects: Versions affected by Certbot issue #10593
gotchaSlow DNS Propagation or Rate Limits with Many Domains: Requesting certificates for a large number of domains (e.g., 15+) in a single `certbot` command with `certbot-dns-route53` can lead to slow DNS propagation or connection resetting errors. The plugin processes updates sequentially, which can be time-consuming or hit API limits for large batches.fixConsider splitting large requests into smaller batches, especially if domains belong to different hosted zones. If experiencing propagation issues, increase the propagation delay using `--dns-route53-propagation-seconds <seconds>`.
affects: All versions
Upgrade
Version history
5.6.0latest on PyPI · released May 11, 2026
Audit
Dependencies
certbotrequiredCore certificate management tool
boto3requiredAWS SDK for Python, required to interact with Route 53 API