Registry / auth-security / certbot-dns-cloudflare

certbot-dns-cloudflare

JSON →
library5.7.0pypypi✓ verified 26d ago

The `certbot-dns-cloudflare` plugin provides a DNS authenticator for Certbot, allowing you to obtain Let's Encrypt certificates using Cloudflare's DNS API. This is particularly useful for wildcard certificates. It is part of the larger Certbot project, currently at version 5.5.0, with minor releases typically aligned with Certbot's bimonthly schedule.

pip install certbot certbot-dns-cloudflare
INSTALL
IMPORT
SIG · CERTBOT-DNS-CLOUDF
C
certbot-dns-cloudflare
auth-securitypythonv5.7.0
Install
9.7s avg
Import
Disk
133MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v5.7.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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 149MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 9.7s · import 0.000s · 149MB
133MB installed
● package 133MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

certbot-dns-cloudflare
This plugin is used via the `certbot` command-line tool, not typically imported in Python code directly by end-users. Its functionality is exposed via CLI flags like `--dns-cloudflare`.

This quickstart script demonstrates how to obtain a certificate for your domain(s) using Certbot and the `certbot-dns-cloudflare` plugin. It creates a temporary credentials file for your Cloudflare API token (read from `CLOUDFLARE_API_TOKEN` environment variable for security) and then executes the `certbot` command. Remember to replace `yourdomain.com` and `your@email.com` with your actual details, and set the `CLOUDFLARE_API_TOKEN` environment variable. Use `--test-cert` for initial testing.

import os import subprocess import tempfile import stat # --- Configuration for your domain and Cloudflare --- DOMAIN = "yourdomain.com" # Replace with your actual domain EMAIL = "your@email.com" # Replace with your actual email # --- Cloudflare API Token (recommended) --- # For production, ensure this token has Zone DNS Write permissions for your domain. # Generate it at: https://dash.cloudflare.com/profile/api-tokens # Set this as an environment variable: export CLOUDFLARE_API_TOKEN="YOUR_TOKEN" CLOUDFLARE_API_TOKEN = os.environ.get('CLOUDFLARE_API_TOKEN', 'YOUR_PLACEHOLDER_TOKEN') if CLOUDFLARE_API_TOKEN == 'YOUR_PLACEHOLDER_TOKEN': print("WARNING: CLOUDFLARE_API_TOKEN environment variable not set. Using a placeholder.") print(" This quickstart will likely fail without a valid token.") print(" Set it using: export CLOUDFLARE_API_TOKEN=\"<YOUR_TOKEN>\"") # --- Create a temporary credentials file --- # This file will store your Cloudflare API token securely. # Certbot requires this file to have restricted permissions (read-only for owner). temp_dir = tempfile.mkdtemp() credentials_path = os.path.join(temp_dir, 'cloudflare.ini') try: with open(credentials_path, 'w') as f: f.write(f"dns_cloudflare_api_token = {CLOUDFLARE_API_TOKEN}\n") # Set permissions: owner read-only (0o400) os.chmod(credentials_path, stat.S_IRUSR) print(f"Created temporary credentials file: {credentials_path}") # --- Construct and run the Certbot command --- # This command obtains a certificate for your domain(s) using Cloudflare DNS. # --dns-cloudflare-propagation-seconds: Adjust if DNS changes are slow to propagate. # --test-cert: Use for testing to avoid hitting Let's Encrypt rate limits. Remove for production. certbot_command = [ "certbot", "certonly", "--dns-cloudflare", f"--dns-cloudflare-credentials={credentials_path}", "--dns-cloudflare-propagation-seconds", "60", "-d", DOMAIN, "-d", f"*.{DOMAIN}", # Uncomment if you need a wildcard certificate "--email", EMAIL, "--agree-tos", "--non-interactive", "--keep-until-expiring", "--test-cert" # IMPORTANT: Use this for initial testing! Remove for actual certificate issuance. ] print("\nAttempting to run Certbot command:") print(f"$ {' '.join(certbot_command)}") # Execute the command result = subprocess.run(certbot_command, capture_output=True, text=True, check=False) # check=False to capture output on error print("\n--- Certbot Output ---") print(result.stdout) if result.stderr: print("\n--- Certbot Errors ---") print(result.stderr) if result.returncode == 0: print("\nSUCCESS: Certbot command completed. Check output for certificate path.") else: print(f"\nFAILURE: Certbot command exited with code {result.returncode}.") print("Please review the output above, ensure your Cloudflare API token is valid and has correct permissions, and that your domain is managed by Cloudflare.") except FileNotFoundError: print("\nERROR: 'certbot' command not found. Please ensure Certbot is installed and in your PATH.") print(" (e.g., pip install certbot certbot-dns-cloudflare or snap install certbot --classic)") except Exception as e: print(f"\nAn unexpected Python error occurred: {e}") finally: # --- Clean up temporary files --- if os.path.exists(credentials_path): os.remove(credentials_path) print(f"\nRemoved temporary credentials file: {credentials_path}") if os.path.exists(temp_dir): os.rmdir(temp_dir) print(f"Removed temporary directory: {temp_dir}")
certbot --version
Debug
Known issues
breakingCertbot 5.0.0 and subsequent versions (including certbot-dns-cloudflare 5.x.x) require Python 3.10 or newer. Users on older Python versions will need to upgrade their Python environment.
fix
Upgrade your Python installation to 3.10 or later. Consider using a `snap` installation of Certbot, which bundles its own compatible Python environment, to avoid system Python conflicts.
affects: >=5.0.0
gotchaThe credentials file containing your Cloudflare API token/key must have restricted permissions (owner read-only, e.g., `0o400`) to prevent unauthorized access. Certbot will refuse to use files with broader permissions.
fix
After creating your `cloudflare.ini` file, set its permissions using `chmod 400 /path/to/cloudflare.ini`. The quickstart code handles this automatically for the temporary file.
affects: All
gotchaCloudflare recommends using API Tokens (granular permissions) over Global API Keys (full account access). While the plugin supports both, API Tokens are more secure and should be preferred. Ensure the token has 'Zone DNS' 'Edit' permissions for the specific zones you intend to manage.
fix
Generate a dedicated API Token at Cloudflare Dashboard > My Profile > API Tokens. Use `dns_cloudflare_api_token = YOUR_TOKEN` in your credentials file. Avoid using your Global API Key (`dns_cloudflare_email` and `dns_cloudflare_api_key`) unless absolutely necessary.
affects: All
gotchaDNS changes need time to propagate across the internet. If Certbot fails with a 'DNS problem' error, it might be due to insufficient propagation time. The default `30` seconds might not always be enough.
fix
Increase the propagation delay using the `--dns-cloudflare-propagation-seconds` flag, e.g., `--dns-cloudflare-propagation-seconds 60` or `120`. Monitor DNS changes with tools like `dig` to determine an appropriate value.
affects: All
gotchaManaging Certbot installations can be complex due to various methods (pip, snap, OS package managers). Mixing methods or using an outdated Certbot installation can lead to plugin not found errors or dependency conflicts.
fix
For most users, especially on Linux, the `snap` installation (`sudo snap install certbot --classic`) is recommended as it's self-contained and handles dependencies. If using `pip`, ensure Certbot and its plugins are installed in the same virtual environment and that the `certbot` command points to that environment.
affects: All
breakingWhen using Cloudflare API tokens with `certbot-dns-cloudflare`, ensure that the `cloudflare` Python package dependency is at version 2.3.1 or newer. Older versions might not correctly handle API tokens, leading to 'Invalid request headers' errors.
fix
Upgrade the `cloudflare` Python package in your Certbot environment: `pip install --upgrade cloudflare`. Ensure it's installed in the same environment as Certbot and its plugins.
affects: All
Upgrade
Version history
5.7.0latest on PyPI · released Jul 15, 2026
Audit
Dependencies
certbotrequiredThis package is a plugin for Certbot and requires Certbot to be installed.
Agent activity
43 hits · last 30 days
node
40
OpenAI (training)
1
Resources
certbot-dns-cloudflare — pip install certbot-dns-cloudflare · libregistry