PyOTP

PyOTP is a Python library for generating and verifying one-time passwords, implementing the open MFA standards RFC 4226 (HOTP) and RFC 6238 (TOTP). It’s the server-side building block for two-factor authentication flows: generate a shared secret, build a otpauth:// provisioning URI that Google Authenticator, Authy, or any compatible app can scan as a QR code, then verify codes the user types back in against a time window or counter.

The library keeps its API deliberately small — TOTP, HOTP, and a parse_uri()/provisioning_uri() pair cover the entire standard — while handling the cryptographic and encoding details (base32 secret padding, HMAC-SHA1/256/512 digest truncation, constant-time comparison) that are easy to get subtly wrong when implemented from scratch. It ships as a zero-dependency, pure-Python package with full type hints.

What You Get

• TOTP and HOTP classes with .now()/.at() code generation and .verify() with configurable valid-window tolerance
• provisioning_uri() to build otpauth:// URIs for QR-code enrollment in Google Authenticator, Authy, and similar apps
• parse_uri() to parse an existing otpauth URI back into a configured TOTP/HOTP object
• random_base32()/random_hex() helpers for generating cryptographically appropriate shared secrets
• Constant-time string comparison for OTP verification to avoid timing side-channel leaks
• A pyotp.contrib.Steam implementation of Steam’s non-standard TOTP variant

Common Use Cases

• Adding two-factor authentication to a web application’s login flow, verifying codes from an authenticator app
• Generating QR-code enrollment links so users can add an account to Google Authenticator or Authy
• Building a custom authenticator or admin tool that needs to generate or check standards-compliant OTP codes
• Preventing TOTP replay attacks by tracking the last-used timecode via verify_and_get_timecode()

Under The Hood

Architecture - The library is organized around a small OTP base class (otp.py) that implements the shared HMAC-based code generation (generate_otp(), base32 secret decoding, big-endian counter-to-bytestring conversion), with HOTP and TOTP subclasses in hotp.py/totp.py adding counter- and time-window semantics respectively. TOTP.timecode() converts a datetime (timezone-aware or naive) into the RFC 6238 counter value, and both subclasses share provisioning_uri()/utils.build_uri() for building otpauth:// URIs and utils.strings_equal() for constant-time verification. The top-level parse_uri() in __init__.py reverses this — parsing an otpauth URI’s scheme, label, and query parameters back into a constructed TOTP/HOTP/Steam instance, with explicit handling for percent-encoded colons in the issuer:account label to avoid a historical mis-parsing bug (GitHub issue #174).

Tech Stack - Pure Python (94% of the codebase) with zero runtime dependencies — only the standard library (hashlib, hmac, base64, datetime, urllib.parse). Packaging uses Hatchling with hatch-vcs for git-tag-based versioning, and the project ships PEP 561 type hints via a py.typed marker. Supports Python 3.8 through 3.13 plus PyPy.

Code Quality - test.py is a single large but thorough test file covering RFC 4226/6238 test vectors, provisioning URI round-trips, edge cases like SHA256/SHA512 digests, and rejecting weak digests (MD5, SHAKE-128) that produce too-short digest sizes. Input validation is explicit throughout (digits must be no greater than 10, input must be positive integer, valid_window cannot be negative), and type hints are used consistently across the small module surface. Ruff and mypy are configured as dev dependencies for linting and type checking.

API Design - The class-based API (pyotp.TOTP(secret), .now(), .verify(code)) requires almost no boilerplate to get a working OTP flow, and mirrors what most authenticator apps expect by default (30-second interval, 6-digit SHA1 codes) while still allowing full customization of digest, digit count, and interval. provisioning_uri()/parse_uri() form a clean encode/decode pair that maps directly onto the QR-code enrollment step most 2FA UIs need.