Certbot

5.5.0 · active · verified Sat Apr 11

Certbot is an easy-to-use ACME client developed by the EFF, designed to automate the process of obtaining and renewing free SSL/TLS certificates from Certificate Authorities like Let's Encrypt. It simplifies the setup of HTTPS on web servers by automatically configuring popular servers like Apache and Nginx. Currently at version 5.5.0, Certbot maintains an active development cycle with regular releases, typically on a monthly or bi-monthly basis.

Warnings

breaking In `v5.0.0`, Certbot removed final instances of `pyopenssl` x509 and PKey objects, and `acme.crypto_util.SSLSocket` was removed. Code directly interacting with these specific internal APIs will break.
Fix: Review your code for direct dependencies on `acme.crypto_util.SSLSocket` or `pyopenssl` x509/PKey objects if you were using Certbot's internal APIs. Most users interacting via CLI will be unaffected.
breaking As of `v5.5.0`, nearly all code for `certbot-nginx` and `certbot-apache` plugins has been moved into private modules within the `certbot` package, which now offers 'apache' and 'nginx' extras. While command-line users should notice no major changes, programmatic users or those with custom plugin integrations might be affected by this architectural shift in package structure and import paths. Existing `certbot-apache` and `certbot-nginx` packages now primarily serve as dependencies that register the plugin functionality.
Fix: Ensure `certbot` is installed with the appropriate extras (`pip install 'certbot[apache]'` or `pip install 'certbot[nginx]'`). If you had custom programmatic interactions with plugin internals, review the new `certbot` package structure.
deprecated The function `acme.crypto_util.make_self_signed_cert` was deprecated in `v5.1.0` and will be removed in a future release. Additionally, the `certbot.ocsp` module was deprecated in `v5.5.0` and will be removed in the next major release.
Fix: Avoid using `acme.crypto_util.make_self_signed_cert` and `certbot.ocsp` in any custom scripts or integrations.
gotcha When requesting certificates with IP address SANs using the standalone or manual plugin (via the `--ip-address` flag introduced in `v5.3.0`), you will also need to pass `--preferred-profile shortlived` for Let's Encrypt's implementation of IP address certificates.
Fix: Include `--preferred-profile shortlived` when requesting IP address SANs with Let's Encrypt to ensure successful issuance: `certbot certonly --standalone --ip-address <your_ip> --preferred-profile shortlived`.
gotcha Deploy directory hooks are now also run when using `certbot certonly` or `certbot run` to get a new certificate, not just during renewals. This change was introduced in `v5.3.0`.
Fix: Be aware that any scripts configured as deploy hooks will execute upon initial certificate issuance via `certonly` or `run` commands, in addition to renewals. Adjust hook logic if this behavior is not desired for initial issuance.

Install

pip install certbot Basic installation (without web server plugins)
pip install 'certbot[apache]' # For Apache plugin pip install 'certbot[nginx]' # For Nginx plugin Installation with web server plugins (recommended for automatic configuration)
sudo apt install certbot python3-certbot-apache # On Debian/Ubuntu for Apache sudo dnf install certbot python3-certbot-nginx # On RHEL/Fedora for Nginx System package manager installation (recommended for server deployments)

Imports

certbot

Certbot is primarily a command-line utility. Direct programmatic import and use of its core functionality is generally not recommended for end-users managing certificates. For programmatic interaction with the ACME protocol, consider using the 'acme' library (from 'from acme import ...').

Certbot is designed for CLI execution on a web server, not as a Python library for direct application integration.

Quickstart

Certbot's primary interface is the command line. These examples show how to obtain and install a certificate for Nginx, obtain a certificate using the webroot method, and perform a renewal. For full automation, `certbot renew` is typically scheduled via a cron job.

# To obtain and install a certificate for example.com using the Nginx plugin:
sudo certbot --nginx -d example.com -d www.example.com

# To obtain a certificate without installing it (e.g., for manual setup):
sudo certbot certonly --webroot -w /var/www/html -d example.com

# To renew all certificates automatically (typically run via cron):
sudo certbot renew --dry-run # Test renewal without actual changes
sudo certbot renew

view raw JSON →