Source: https://mokxi.com/libraries/ntpclient
Updated: 2026-11-17

Libraries / Network

Arduino library · Network

# NTPClient: the time of day from an NTP server

Yes, with limits. You can use the NTPClient library online in Mokxi with nothing to install, and the sketch runs in your browser. Part of it is not simulated, and the notes below say which. The example below, "ESP32 NTP clock on a TM1637 display", runs on the ESP32 DevKit V1.

Run the example in Mokxi See the calls

Built in on Mokxi: #include <NTPClient.h> and it builds, with nothing to install. Free, and no account needed.

## What NTPClient does

An ESP8266 or ESP32 has no idea what time it is when it powers up. NTPClient, from the arduino-libraries organization, fixes that by asking a Network Time Protocol server over UDP and keeping the answer: after one successful update() the board can print the hours, minutes and seconds, or hand back the Unix epoch for a logger or a schedule.

You build it on a WiFiUDP object, name a server pool such as pool.ntp.org, give an offset from UTC in seconds and an update interval in milliseconds. Call begin() once WiFi is up and update() in loop(); update() only asks the server again when the interval has passed, so calling it every pass is cheap. forceUpdate() asks right away.

Two gaps surprise people. The library knows nothing about daylight saving, so the offset is fixed until you change it with setTimeOffset(). And the official release has no date function: getFormattedTime() gives HH:MM:SS only, so turn getEpochTime() into a date with gmtime() or TimeLib. In Mokxi there is no UDP and no NTP server, so the time comes from the simulation’s own clock, which starts at 2026-01-01 00:00:00 UTC, and the serial monitor says so.

Library Manager name | NTPClient

Author | Fabrice Weinberg (arduino-libraries)

Include | #include <NTPClient.h>

Boards | ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32, ESP8266 NodeMCU, Raspberry Pi Pico W, Arduino Uno R4 WiFi

In the simulator | Runs, with a gap the note below names.

## Install it

It builds on ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32, ESP8266 NodeMCU, Raspberry Pi Pico W, Arduino Uno R4 WiFi.

In Mokxi it is built in: #include <NTPClient.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "NTPClient" by Fabrice Weinberg (arduino-libraries) from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add NTPClient to lib_deps in PlatformIO. Mokxi follows the calls of release 3.2.1, so a sketch written here builds there too.

What to know in the simulator: NTP is simulated, so this is not the real current time: the network carries no UDP and cannot reach an NTP server, and the simulation does not know today’s date. An update while the board is on the network sets the simulation’s own clock, 2026-01-01 00:00:00 UTC at power-up plus the seconds since (plus the offset), the same clock configTime() and http://time.mokxi/ give, and the serial monitor says so once.

- ESP32-C3
- ESP32-C6
- Seeed XIAO ESP32-C3
- ESP32-C3 SuperMini
- Seeed XIAO ESP32-C6
- ESP32 DevKit
- ESP32-DevKitC V4
- LOLIN32 Lite
- Wemos D1 R32
- Cheap Yellow Display
- TTGO T-Display
- ESP32-S3-DevKitC-1
- Seeed XIAO ESP32-S3
- Arduino Nano ESP32
- ESP8266 NodeMCU
- Raspberry Pi Pico W
- Arduino Uno R4 WiFi

## The calls you will use

In the order a sketch meets them.

### NTPClient timeClient(ntpUDP, "pool.ntp.org", 3600, 60000)

Creates the client on a WiFiUDP you declared first, with the server, an offset of 3600 seconds (UTC+1) and a refresh every 60 seconds.

### timeClient.begin()

Opens the UDP port. Call it after WiFi.status() reports WL_CONNECTED.

### timeClient.update()

Asks the server again only when the update interval has passed, and returns true when the time was refreshed. Put it in loop().

### timeClient.forceUpdate()

Asks the server now, whatever the interval, and returns true on an answer. Handy once in setup() so the first reading is right.

### timeClient.getFormattedTime()

The local time as a String in HH:MM:SS form, offset included.

### timeClient.getEpochTime()

Seconds since 1 January 1970, with the offset added. Pass it to gmtime() or TimeLib for the date.

### timeClient.getHours()

The hour, 0 to 23. getMinutes() and getSeconds() work the same way, and getDay() gives 0 for Sunday to 6 for Saturday.

### timeClient.setTimeOffset(-18000)

Changes the offset in seconds, here UTC-5. Call it again when daylight saving starts or ends.

## Example: ESP32 NTP clock on a TM1637 display

On the ESP32 DevKit V1. It runs in the browser exactly as printed.

sketch.ino · ESP32 DevKit V1

Open it in the editor, wired and ready to run · ESP32 NTP clock on a TM1637 display: the project page

## Common errors and how to fix them

### The time prints as 00:00:00 or a 1970 date

No answer has arrived yet. Make sure WiFi is connected before begin(), call forceUpdate() in setup() and check isTimeSet() before printing. On a real network, a firewall that blocks UDP port 123 gives the same symptom.

### The clock is off by exactly some number of hours

The offset is in seconds, not hours: UTC+2 is 7200, UTC-5 is -18000. NTPClient also ignores daylight saving, so in summer you add the extra 3600 yourself, or use ezTime or the Timezone library to work it out.

### 'class NTPClient' has no member named 'getFormattedDate'

getFormattedDate() came from a fork (taranais/NTPClient), not the official release this page covers. Use getEpochTime() and convert it with gmtime() or TimeLib’s year(), month() and day() to print the date.

## Questions and answers

### NTPClient or configTime() on an ESP32?

configTime() is built into the ESP32 and ESP8266 cores, handles time zones through a POSIX string and keeps the C library’s clock in sync on its own. NTPClient is simpler to read and works on any board with a UDP stack.

### Why does Mokxi say the time is January 2026?

The simulator cannot reach an NTP server, so update() sets the time from the simulation’s own clock, which starts at 2026-01-01 00:00:00 UTC and counts up from power-on. The code path is the same as on a board.

## Keep going

### Learn

- ESP32 Not Connecting to WiFi: Causes and Fixes
- Arduino millis(): Timers and Multiple Tasks

### More network libraries

- PubSubClient
- MQTT
- Blynk
- ThingSpeak
- WiFiManager
- WiFi, HTTPClient and WebServer (ESP32 core)
- WebSockets
- UniversalTelegramBot

Every built-in library · Open the editor

## Try NTPClient without installing anything

Open the example, change the sketch, and keep your version in a free account.

Start building free

Open the editor
