Skip to main content

PyOTP - The Python One-Time Password Library

PyOTP is a Python library for generating and verifying one-time passwords. It can be used to implement two-factor (2FA) or multi-factor (MFA) authentication methods in web applications and in other systems that require users to log in.

Open MFA standards are defined in RFC 4226 (HOTP: An HMAC-Based One-Time Password Algorithm) and in RFC 6238 (TOTP: Time-Based One-Time Password Algorithm). PyOTP implements server-side support for both of these standards. Client-side support can be enabled by sending authentication codes to users over SMS or email (HOTP) or, for TOTP, by instructing users to use Google Authenticator, Authy, or another compatible app. Users can set up auth tokens in their apps easily by using their phone camera to scan otpauth:// QR codes provided by PyOTP.

Implementers should read and follow the HOTP security requirements and TOTP security considerations sections of the relevant RFCs. At minimum, application implementers should follow this checklist:

  • Ensure transport confidentiality by using HTTPS

  • Ensure HOTP/TOTP secret confidentiality by storing secrets in a controlled access database

  • Deny replay attacks by persisting the last accepted OTP counter for each credential and rejecting reused counters. For TOTP, use verify_and_get_timecode() as described in Preventing replay attacks below.

  • Throttle (rate limit) brute-force attacks against your application’s login functionality (see RFC 4226, section 7.3 and NIST SP 800-63B, section 3.2.2)

  • When implementing a “greenfield” application, consider supporting FIDO U2F/WebAuthn in addition to or instead of HOTP/TOTP. U2F uses asymmetric cryptography to avoid using a shared secret design, which strengthens your MFA solution against server-side attacks. Hardware U2F also sequesters the client secret in a dedicated single-purpose device, which strengthens your clients against client-side attacks. And by automating scoping of credentials to relying party IDs (application origin/domain names), U2F adds protection against phishing attacks. One implementation of FIDO U2F/WebAuthn is PyOTP’s sister project, PyWARP.

We also recommend that implementers read and follow the following resources:

Quick overview of using One Time Passwords on your phone

  • OTPs involve a shared secret, stored both on the phone and the server

  • OTPs can be generated on a phone without internet connectivity

  • OTPs should always be used as a second factor of authentication (if your phone is lost, you account is still secured with a password)

  • Google Authenticator and other OTP client apps allow you to store multiple OTP secrets and provision those using a QR Code

Installation

pip install pyotp

Usage

Time-based OTPs

import pyotp

totp = pyotp.TOTP('base32secret32323232323232')
totp.now()  # Current OTP; changes with the clock.

# A fixed Unix timestamp makes these example outputs reproducible.
totp.at(1234567890) # => '763850'
totp.verify('763850', for_time=1234567890) # => True
totp.verify('763850', for_time=1234567920) # => False

Preventing replay attacks

TOTP.verify() and TOTP.verify_and_get_timecode() are stateless: they can accept the same OTP repeatedly while it remains valid. To prevent reuse, call verify_and_get_timecode() and persist its returned timecode for each credential in a database shared by all application workers. The timecode identifies the matching TOTP interval; it is not the wall-clock timestamp when verification occurred. Reject a timecode that is less than or equal to the last accepted timecode.

verify_and_get_timecode() raises pyotp.OTPVerificationError (a subclass of pyotp.PyOTPError) if the OTP does not match within the allowed window. Successful verification always returns an integer timecode.

The check and update must be atomic, so two concurrent requests cannot both accept the same timecode. For example, the following function uses a sqlite3.Connection named db and a totp_credentials table with one existing row per credential, an id primary key, and a nullable integer last_timecode column. Initialize last_timecode to NULL for a new credential. totp and credential_id must refer to the same credential.

import pyotp

def verify_totp_once(db, credential_id, totp, otp):
    try:
        matched_timecode = totp.verify_and_get_timecode(otp)
    except pyotp.OTPVerificationError:
        return False

    with db:
        updated = db.execute(
            "UPDATE totp_credentials SET last_timecode = ? "
            "WHERE id = ? AND (last_timecode IS NULL OR last_timecode < ?)",
            (matched_timecode, credential_id, matched_timecode),
        )
    return updated.rowcount == 1

Grant authentication only when this function returns True, after the database transaction has committed. If you enable valid_window, persist the returned matching timecode, which may differ from the server’s current timecode.

Counter-based OTPs

import pyotp

hotp = pyotp.HOTP('base32secret32323232323232')
hotp.at(0) # => '995369'
hotp.at(1) # => '511453'
hotp.at(1401) # => '666948'

# OTP verified with a counter
hotp.verify('666948', 1401) # => True
hotp.verify('666948', 1402) # => False

Generating a Secret Key

A helper function is provided to generate a 32-character base32 secret, compatible with Google Authenticator and other OTP apps:

pyotp.random_base32()

Some applications want the secret key to be formatted as a hex-encoded string:

pyotp.random_hex()  # returns a 40-character hex-encoded secret

Google Authenticator Compatible

PyOTP works with the Google Authenticator iPhone and Android app, as well as other OTP apps like Authy. PyOTP includes the ability to generate provisioning URIs for use with the QR Code scanner built into these MFA client apps:

pyotp.totp.TOTP('JBSWY3DPEHPK3PXPJBSWY3DP').provisioning_uri(name='alice@google.com', issuer_name='Secure App')

>>> 'otpauth://totp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXPJBSWY3DP&issuer=Secure%20App'

pyotp.hotp.HOTP('JBSWY3DPEHPK3PXPJBSWY3DP').provisioning_uri(name="alice@google.com", issuer_name="Secure App", initial_count=0)

>>> 'otpauth://hotp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXPJBSWY3DP&issuer=Secure%20App&counter=0'

This URL can then be rendered as a QR Code (for example, using https://github.com/soldair/node-qrcode) which can then be scanned and added to the users list of OTP credentials.

Parsing these URLs is also supported:

pyotp.parse_uri('otpauth://totp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXPJBSWY3DP&issuer=Secure%20App')

>>> <pyotp.totp.TOTP object at 0xFFFFFFFF>

pyotp.parse_uri('otpauth://hotp/Secure%20App:alice%40google.com?secret=JBSWY3DPEHPK3PXPJBSWY3DP&issuer=Secure%20App&counter=0')

>>> <pyotp.hotp.HOTP object at 0xFFFFFFFF>

Working example

Scan the following barcode with your phone’s OTP app (e.g. Google Authenticator):

https://quickchart.io/qr?size=250&text=otpauth%3A%2F%2Ftotp%2Falice%40google.com%3Fsecret%3DJBSWY3DPEHPK3PXPJBSWY3DP

Now run the following and compare the output:

import pyotp
totp = pyotp.TOTP("JBSWY3DPEHPK3PXPJBSWY3DP")
print("Current OTP:", totp.now())

Adjusting the minimum seed length

RFC 4226, section 4 requires a minimum seed length of 128 bits and recommends 160 bits. NIST SP 800-63B-4, section 3.1.4.1 requires the secret key and its algorithm to provide at least 112 bits of security strength. By default, PyOTP checks that secret inputs are at least 112 bits long after Base32 decoding. To specify a different minimum seed length, subclass pyotp.TOTP or pyotp.HOTP and adjust the min_secret_length_bits class variable inherited from pyotp.OTP:

import pyotp

class TOTP128(pyotp.TOTP):
    min_secret_length_bits = 128

class HOTP128(pyotp.HOTP):
    min_secret_length_bits = 128

secret = pyotp.random_base32()
totp = TOTP128(secret)
hotp = HOTP128(secret)

The minimum applies when constructing an instance and whenever its secret is decoded to generate or verify an OTP.

Third-party contributions

The following third-party contributions are not described by a standard, not officially supported, and provided for reference only:

  • pyotp.contrib.Steam(): An implementation of Steam TOTP. Uses the same API as pyotp.TOTP().

Versioning

This package follows the Semantic Versioning 2.0.0 standard. To control changes, it is recommended that application developers pin the package version and manage it using uv or similar. For library developers, pinning the major version is recommended.

Metadata

Release files for PyOTP 2.12.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for PyOTP 2.12.1
File Size Uploaded Provenance Actions
pyotp-2.12.1.tar.gz 27.5 kB With provenance Details for pyotp-2.12.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for PyOTP 2.12.1
File Interpreter ABI Platform Actions
pyotp-2.12.1-py3-none-any.whl Python 3 none any Details for pyotp-2.12.1-py3-none-any.whl

Total release size: 44.5 kB

Release files / pyotp-2.12.1.tar.gz

Download URL pyotp-2.12.1.tar.gz
Size 27.5 kB
Tags Source
SHA-256 checksum
How to use checksums
8d0c4192f3c5d1b1a8792df23b9d8acbb7e70abd2b160962af55c5700edbd236
BLAKE2b-256 checksum
How to use checksums
70d7fe43d6cfd1e80081a374c612df6b6555205a7ab761fdd6ba6e30435fd963
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / pyotp-2.12.1-py3-none-any.whl

Download URL pyotp-2.12.1-py3-none-any.whl
Size 17.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2f65978d0a0afe5588ec960c810cbb974ba1957ffbf29775d8d4e1b2d4b8984c
BLAKE2b-256 checksum
How to use checksums
32d5ca399f55b474357c42b8d0ee1c0222a22e6f88bbf4588130b75737c3b73b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for PyOTP 2.12.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pyotp-2.12.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page