certbot-nginx

5.5.0 verified Fri May 01 auth: no python

Official Nginx plugin for Certbot, enabling automatic TLS certificate issuance and renewal for Nginx servers on Linux. Current version 5.5.0 supports Python >=3.10. Released approximately quarterly.

pip install certbot-nginx

Common errors

error certbot: error: unrecognized arguments: --nginx ↓

cause certbot-nginx plugin not installed or not registered.

fix

Run 'pip install certbot-nginx' and ensure it is in the same Python environment as certbot.

error No module named 'certbot_nginx' ↓

cause Plugin package not installed.

fix

Install with 'pip install certbot-nginx'.

error AttributeError: module 'certbot_nginx' has no attribute 'NginxConfigurator' ↓

cause Importing from the top-level namespace which was removed in v5.5.0.

fix

Use 'from certbot_nginx._internal.configurator import NginxConfigurator'.

Warnings

breaking In v5.5.0, most certbot-nginx code was moved into private modules within the certbot package. Third-party code importing from certbot_nginx may break. ↓

fix Switch imports to 'certbot_nginx._internal' or rely on certbot's extras: 'certbot[nginx]'.

deprecated Python 3.8 and 3.9 support dropped; requires Python >=3.10. ↓

fix Upgrade to Python 3.10+.

gotcha certbot-nginx modifies Nginx configuration files. Always backup your configs before running. ↓

fix Run 'certbot --nginx --dry-run' first to preview changes.

Imports

NginxCompatibility

wrong

from certbot_nginx.configurator import NginxConfigurator

correct

from certbot_nginx._internal.configurator import NginxConfigurator

Code was moved into private modules in certbot package in v5.5.0; internals are unstable.

NginxConfigurator

wrong

from certbot_nginx import NginxConfigurator

correct

from certbot_nginx._internal.configurator import NginxConfigurator

Direct import from top-level package removed in v5.5.0.

Quickstart

Run certbot with the Nginx plugin to obtain and install a TLS certificate. For production, ensure Nginx server blocks exist before running.

import subprocess
import sys

# Unattended install of cert for example.com using certbot-nginx
result = subprocess.run([
    sys.executable, '-m', 'certbot', '--nginx',
    '-d', 'example.com',
    '--non-interactive', '--agree-tos',
    '-m', 'admin@example.com'
], capture_output=True, text=True)
print(result.stdout)
if result.returncode != 0:
    print(result.stderr, file=sys.stderr)