Source: https://mokxi.com/libraries/preferences
Updated: 2026-11-02

Libraries / Data and time
Arduino library · Data and time

# ESP32 Preferences: keep settings by name across resets

Preferences is the ESP32 core’s replacement for EEPROM.h. Instead of picking byte addresses, you store values under a key inside a namespace, and the core keeps them in the NVS partition of the flash, which spreads writes around so the flash wears evenly. A WiFi password, a calibration offset or a boot counter all fit.

Open the example in the editor See the calls

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

## What Preferences (ESP32 core) does

Every use is begin(), the gets and puts, then end(). begin("my-app", false) opens a namespace read-write (true opens it read-only). Each get takes a default that comes back when the key has never been written, which is what makes a first boot work without special code.

Keys and namespace names are at most 15 characters, and the type you read must match the type you wrote: a value stored with putInt() does not come back from getUInt(). NVS also has a fixed size, around 20 KB on the default partition table, so it is for settings, not for logging data.

Library Manager name | Preferences (ESP32 core)

Author | Espressif

Include | #include <Preferences.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

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.

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

On a real board it comes with the board package (Espressif), so the Arduino IDE has it as soon as the board is installed: there is nothing to add from the Library Manager.

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

## The calls you will use

In the order a sketch meets them.

### Preferences preferences

The object, usually a global so setup() and loop() can both use it.

### preferences.begin("my-app", false)

Opens a namespace, creating it if needed. false means read-write. Returns false if it could not be opened.

### preferences.getUInt("counter", 0)

Reads an unsigned int, or the default 0 when the key is not there. There is a get for every type: getInt, getFloat, getBool, getString, getBytes.

### preferences.putUInt("counter", counter)

Writes the value under the key and returns the number of bytes stored, 0 on failure.

### preferences.putString("ssid", ssid)

Stores a String or a C string. getString("ssid", "") reads it back.

### preferences.isKey("ssid")

True when the key exists, for telling "never set" apart from a stored default.

### preferences.remove("counter")

Deletes one key. preferences.clear() deletes every key in the open namespace.

### preferences.end()

Closes the namespace. Open another with begin() to switch.

## Example: Keep settings by name

On the ESP32-C3-DevKitM-1. It runs in the browser exactly as printed.

sketch.ino · ESP32-C3-DevKitM-1

Open it in the editor, wired and ready to run

## Common errors and how to fix them

### A value always reads back as the default

Usually the key is longer than 15 characters and the write failed, or the read uses a different type than the write (putInt then getUInt). Check the number putUInt() returns, and read with the matching get.

### nvs_open failed: NOT_FOUND

The namespace was opened read-only, begin("name", true), before anything was ever written to it. Open it read-write the first time, or ignore the message: the gets still return their defaults.

### The boot counter in Mokxi always says 1

Mokxi’s ESP32 models have no flash behind Preferences, so values are kept in RAM for the run and gone after a reset. On a real board the same sketch counts up, since NVS survives power cycles.

## Keep going

### Learn

- ESP32 Preferences Library: Save Settings, Example
- Arduino EEPROM: Read, Write, put() and get()

### More data and time libraries

- QRCode
- Madgwick
- PID
- TimerOne
- MsTimer2
- Low-Power
- RTClib
- DS1307RTC

Every built-in library · Open the editor

## Try Preferences (ESP32 core) without installing anything

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

Start building free

Open the editor