Registry / auth-security / acme
library5.7.0pypypi✓ verified 25d ago

The `acme` library is a low-level, comprehensive Python implementation of the Automated Certificate Management Environment (ACME) protocol, primarily maintained as part of the Certbot project. It enables programmatic certificate issuance, renewal, and management, supporting Let's Encrypt and other ACME-compatible certificate authorities. Currently at version 5.5.0, `acme` follows the release cadence of Certbot, typically seeing several updates per year, often driven by new ACME RFCs or internal Certbot architectural changes.

pip install acme
INSTALL
IMPORT
SIG · ACME
A
acme
auth-securitypythonv5.7.0
Install
3.3s avg
Import
659ms
Disk
38MB
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.676s · 39.7MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.3s · import 0.642s · 40MB
38MB installed
● package 38MB
Code
Verified usage

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

ClientV2
from acme import client
messages
from acme import messages
challenges
from acme import challenges
josepy
import josepy as jose
crypto_util
from acme import crypto_util
from certbot import crypto_util
While developed with Certbot, crypto_util is part of the acme package itself.

This quickstart demonstrates the absolute minimum to initialize the `acme` client and register an account with an ACME server (like Let's Encrypt staging). Note that `acme` is a low-level library; most users will prefer a higher-level client like Certbot for end-to-end certificate management. This example creates an RSA account key, sets up the network client, fetches the directory, and attempts to register a new ACME account, handling potential conflicts if the account already exists. It uses the Let's Encrypt staging environment by default.

import os from cryptography.hazmat.primitives.asymmetric import rsa from cryptography.hazmat.backends import default_backend from acme import client from acme import messages import josepy as jose # This is the staging ACME URL for Let's Encrypt DIRECTORY_URL = os.environ.get('ACME_DIRECTORY_URL', 'https://acme-staging-v02.api.letsencrypt.org/directory') def run_acme_client(): # 1. Create a new ACME account private key acc_key_pem = rsa.generate_private_key( public_exponent=65537, key_size=2048, backend=default_backend() ) acc_key = jose.JWK.from_pem(acc_key_pem.private_bytes( encoding=jose.serialization.Encoding.PEM, format=jose.serialization.PrivateFormat.PKCS8, encryption_algorithm=jose.serialization.NoEncryption() )) # 2. Initialize the client network net = client.ClientNetwork(acc_key, user_agent="my-acme-client/1.0") # 3. Get the ACME directory object directory = messages.Directory.from_json(net.get(DIRECTORY_URL).json()) # 4. Create the ACME client acme_client = client.ClientV2(directory, net=net) # 5. Register a new account (or load existing) # email_contact is optional for staging/testing new_reg = messages.NewRegistration( terms_of_service_agreed=True, contact=('mailto:test@example.com',) if 'test@example.com' in os.environ.get('ACME_EMAIL', '') else None ) try: regr = acme_client.new_account(new_reg) print(f"Account created/loaded: {regr.uri}") except client.errors.ConflictError as e: # Account already exists, retrieve it print(f"Account already exists, retrieving: {e.uri}") regr = acme_client.query_registration(messages.RegistrationResource(uri=e.uri, body=new_reg)) print("ACME client initialized and account registered.") return acme_client, regr if __name__ == "__main__": acme_client_instance, account_resource = run_acme_client()
Debug
Known issues
breakingMajor architectural shift in version 5.0.0 (aligned with Certbot 5.0.0) removed `acme.crypto_util.SSLSocket`, `acme.crypto_util.probe_sni`, and TLS-ALPN related challenge classes (`acme.challenges.TLSALPN01Response`, `acme.challenges.TLSALPN01`, `acme.standalone.TLSServer`, `acme.standalone.TLSALPN01Server`). This also removed final `pyopenssl` x509 and PKey objects usage within `acme`'s core cryptography, favoring `cryptography` library objects.
fix
Migrate any code using these removed classes/functions to their `cryptography` equivalents or alternative ACME challenge methods. Review the `certbot` changelog for detailed migration paths. For TLS-ALPN, re-evaluate if still necessary as its support was deprecated and then removed.
affects: >=5.0.0
deprecatedThe function `acme.crypto_util.make_self_signed_cert` was deprecated in Certbot 5.1.0 and is slated for removal. This indicates a shift away from generating self-signed certificates directly within the `acme` library.
fix
Avoid using `acme.crypto_util.make_self_signed_cert`. If self-signed certificates are required, use `cryptography`'s API directly or an external tool.
affects: >=5.1.0
breakingVersion 2.0.0 (aligned with Certbot 2.0.0) removed support for pre-RFC 8555 ACME versions and related deprecated messaging constructs like `acme.messages.OLD_ERROR_PREFIX`. It also removed the `source_address` argument from `acme.client.ClientNetwork` and several deprecated attributes from `acme.messages.Directory` and `acme.messages.Authorization`.
fix
Ensure all ACME interactions adhere to RFC 8555. Update any references to `OLD_ERROR_PREFIX` or the removed `Directory` and `Authorization` attributes. The `source_address` removal requires alternative methods for binding to specific local IPs if needed.
affects: >=2.0.0
gotchaThe `acme` library's cryptographic requirements are tightly coupled with `certbot`'s and have increased over time. As of Certbot 3.2.0, `acme` requires `cryptography>=43.0.0` and `pyOpenSSL>=25.0.0`.
fix
Ensure your environment meets these minimum dependency versions to avoid runtime errors, especially when upgrading `acme` or `certbot`.
affects: >=3.2.0
Errors
Common errors & fixes
ValueError: Invalid version. The only valid version for X509Req is 0.
This error occurs when using acme v1.23.0 with pyOpenSSL>=23.2.0 on Python 3.6, due to an invalid version being set in the CSR.
fix
Downgrade pyOpenSSL to version 23.1.0 by running: pip install 'pyOpenSSL==23.1.0'.
acme.errors.SchemaValidationError: JSON schema ACME object validation error.
This error indicates that the ACME object does not conform to the expected JSON schema.
fix
Ensure that the ACME object being processed adheres to the correct JSON schema as defined in the acme library documentation.
acme.errors.MissingNonce: Server response nonce error.
This error occurs when the ACME server's response lacks the required Replay-Nonce header field.
fix
Verify that the ACME server is functioning correctly and that the client is handling nonce values appropriately.
acme.errors.ValidationError: Error for authorization failures.
This error signifies that one or more authorization resources are invalid, often due to failed domain validation challenges.
fix
Check the authorization resources for errors and ensure that domain validation challenges are correctly configured and passing.
acme.errors.TimeoutError: Error for when polling an authorization or an order times out.
This error indicates that the client timed out while waiting for an authorization or order to complete.
fix
Increase the timeout settings in the client configuration or investigate potential network issues causing the delay.
Upgrade
Version history
5.7.0latest on PyPI · released Jul 15, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or later.
josepyrequiredCryptography utilities for JOSE (JSON Object Signing and Encryption).
cryptographyrequiredCore cryptographic primitives for Python.
requestsrequiredHTTP library for making requests to ACME servers.
pyopensslrequiredOpenSSL wrapper for Python (though usage has been reduced/deprecated in favor of 'cryptography').
Agent activity
61 hits · last 30 days
node
54
OpenAI (training)
1
Resources
acme — pip install acme · libregistry