{"id":4653,"library":"ntplib","title":"Python NTP Library","description":"ntplib is a Python module offering a simple interface to query Network Time Protocol (NTP) servers. It provides functionality to request time and status information from NTP servers and includes utility functions to translate NTP field values (like mode or leap indicator) into human-readable text. It is a pure Python library with no external dependencies beyond core modules, ensuring broad compatibility across various platforms. The latest release, 0.4.0, was on May 28, 2021, indicating a mature library with a moderate release cadence.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/cf-natali/ntplib","tags":["network","ntp","time-synchronization","client"],"install":[{"cmd":"pip install ntplib","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"Imports the entire ntplib module.","symbol":"ntplib","correct":"import ntplib"},{"note":"Imports the NTPClient class directly for common usage.","symbol":"NTPClient","correct":"from ntplib import NTPClient"}],"quickstart":{"code":"import ntplib\nfrom time import ctime\n\ndef get_ntp_time(server='pool.ntp.org', version=3):\n    \"\"\"Queries an NTP server and prints selected response fields.\"\"\"\n    try:\n        client = ntplib.NTPClient()\n        response = client.request(server, version=version)\n        print(f\"NTP Server: {server}\")\n        print(f\"Offset: {response.offset:.4f} seconds\")\n        print(f\"Version: {response.version}\")\n        print(f\"NTP Time: {ctime(response.tx_time)}\")\n        print(f\"Leap Indicator: {ntplib.leap_to_text(response.leap)}\")\n        print(f\"Root Delay: {response.root_delay:.4f} seconds\")\n        # ref_id_to_text may take stratum as a second argument in newer versions\n        print(f\"Reference ID: {ntplib.ref_id_to_text(response.ref_id, response.stratum)}\")\n    except ntplib.NTPException as e:\n        print(f\"NTP request failed: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    # Use a common NTP pool server\n    get_ntp_time('pool.ntp.org')\n    # You can also try other servers like 'time.google.com' or 'ntp.org'\n    # get_ntp_time('time.google.com')","lang":"python","description":"This quickstart demonstrates how to create an `NTPClient` instance, send a request to a public NTP server, and access key fields from the `NTPResponse` object, including calculated offset and various NTP status indicators."},"warnings":[{"fix":"Upgrade to `ntplib` version 0.4.0 or higher. If unable to upgrade, avoid `ntplib.stratum_to_text()` or handle potential `NTPException` errors.","message":"A bug in `ntplib` version 0.3.3 could cause exceptions when attempting to translate the `stratum` field to text using utility functions. This issue was resolved in version 0.4.0.","severity":"breaking","affected_versions":"<=0.3.3"},{"fix":"Ensure that UDP port 123 is open in any local or network firewalls, and that no ACLs are blocking NTP traffic.","message":"NTP requests require UDP port 123 to be open for both outbound requests and inbound responses. Firewall rules or network access control lists (ACLs) blocking this port will prevent `ntplib` from successfully communicating with NTP servers.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For non-blocking operations, execute `NTPClient.request()` in a dedicated thread (e.g., using `threading` or `concurrent.futures`) or integrate with an asynchronous framework (e.g., `asyncio`) by wrapping the blocking call, though `ntplib` itself does not offer native async support.","message":"The `NTPClient.request()` method is a blocking call. In applications requiring high concurrency or responsiveness, calling this method directly in the main thread can cause freezes or performance issues. Consider running NTP requests in a separate thread or using asynchronous execution.","severity":"gotcha","affected_versions":"All versions"},{"fix":"On PythonAnywhere, use a paid account which offers broader network access, or explore alternative methods for time synchronization if `ntplib` is used solely for timestamping (e.g., `datetime.now()` for local time or a whitelisted API for external time if available).","message":"Users of PythonAnywhere's free tier may encounter `Errno 1: Operation not permitted` errors when attempting to use `ntplib`. This is due to platform-specific outbound network restrictions on non-whitelisted domains.","severity":"gotcha","affected_versions":"All versions on restricted platforms"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}