Have a project in mind? Let's talk.

ESP32 PSRAM is external pseudo-static RAM that sits next to the flash chip on many ESP32-S3 modules, and it is the difference between an AI or audio project that fits and one that keeps rebooting. Espressif's documentation puts the baseline plainly: the ESP32-S3 carries a few hundred kilobytes of internal RAM on die, and it can map up to 32 MB of external PSRAM into its address space, where, with certain restrictions, it behaves like internal data RAM. Enabling it takes one menu setting in Arduino IDE or a few configuration options in ESP-IDF, but the wrong choice produces an immediate reboot loop. This guide covers identification, enablement, allocation strategy and the traps. Source: Support for External RAM, ESP-IDF Programming Guide
The enable setting depends on the exact module. Espressif's Arduino troubleshooting guide asks you to read the module shielding: the module family is printed near the top, right under the ESP logo, for example ESP32-S3-WROOM-1 or WROOM-2, and a small version code sits in the bottom-left corner, often too small to read without a camera and careful lighting. You then match the module and code against Espressif's table to learn whether the PSRAM is Quad SPI or Octal SPI. WROOM-2 modules are always OPI. Source: Troubleshooting, Arduino ESP32 documentation
On the board itself, ESP32-S3 supports PSRAM connected in parallel with the SPI flash chip, sharing the same SPI bus. That physical arrangement is why flash and PSRAM settings are configured together in ESP-IDF, and why voltage, mode and frequency choices must agree across both chips. Two hardware facts follow from this. PSRAM chips come in 1.8 V and 3.3 V variants, and the PSRAM working voltage must match the flash working voltage; for a 1.8 V chip, GPIO45 must be strapped high at boot or the eFuses must fix VDD_SPI at 1.8 V, and skipping this can physically damage the PSRAM or flash. Also, ESP-IDF currently supports only Espressif-branded PSRAM chips such as ESP-PSRAM32 and ESP-PSRAM64, so a custom third-party chip is not guaranteed to work with the SDK. Source: Support for External RAM, ESP-IDF Programming Guide
Once you know the interface type, the Arduino step is one menu. Espressif's guide says an empty result in its table means no change is needed; otherwise select Tools, then PSRAM, then QSPI PSRAM for Quad parts or OPI PSRAM for Octal parts. This is not optional polish: uploading to a QSPI or OPI board with default settings produces a boot loop with a PSRAM-related error, which is the failure most people meet first. Espressif lists this exact symptom in its troubleshooting documentation and points at the Tools menu as the fix. If your board reboots the moment the sketch starts, this setting is the first thing to check, before you suspect your code. Source: Troubleshooting, Arduino ESP32 documentation
In ESP-IDF, enable external RAM support in menuconfig and then match the PSRAM type to the hardware through CONFIG_SPIRAM_MODE, choosing Quad or Octal. Espressif's flash and PSRAM configuration guide explains the terminology that trips people up: the line mode is the number of signals carrying data in the SPI data phase, and combinations are written as F4R4 for Quad flash with Quad PSRAM. The flash line mode and sample mode must also match the board, and Octal flash parts are selected with their own configuration item. The guide notes that a higher line mode means a faster SPI data phase, that DDR sampling is faster than SDR, and that Quad flash supports STR mode only while Octal flash may support STR, DTR or both depending on the flash model and vendor. Mode and frequency combinations that the chip does not support are a configuration error, not a firmware bug, so the fix lives in menuconfig rather than in your code. Source: Configure SPI Flash and External RAM, ESP-IDF Programming Guide
ESP-IDF offers three integration modes through CONFIG_SPIRAM_USE. The first integrates PSRAM into the memory map only. The second adds it to the capabilities-based heap allocator, so code requests it explicitly with heap_caps_malloc using the MALLOC_CAP_SPIRAM flag and frees it with the normal free call. The third, and the default, makes PSRAM allocatable through an ordinary malloc, so existing code uses the external memory without being rewritten. There is a subtlety worth knowing in the explicit mode: once PSRAM is added to the heap allocator it is also tagged MALLOC_CAP_DEFAULT, so a generic heap_caps_malloc call asking for default-capable memory can still return a PSRAM pointer. Code that truly needs internal RAM must say so. Source: Support for External RAM, ESP-IDF Programming Guide
The default needs guardrails. CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL sets a size threshold below which allocations prefer internal memory, so small control structures keep fast RAM. Because some buffers can only live in internal memory, CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL reserves a pool of DMA-capable internal RAM at startup; explicit requests for DMA-capable internal memory are served from that pool preferentially, and plain malloc can only dip into it after the other internal heaps are exhausted. Static task buffers can also be placed in external RAM with xTaskCreateStatic when its configuration option is enabled. Source: Support for External RAM, ESP-IDF Programming Guide
PSRAM is memory-mapped, but it is not identical to internal RAM. Some buffers must stay internal, which is why the reserved DMA pool exists. Espressif also documents a deep-sleep trap: calling the deep-sleep start function from a task whose stack lives in PSRAM logs an error and proceeds anyway, and the device will likely crash when the cache is disabled during the sleep transition. The safe variant returns an error cleanly instead, and Espressif's advice is to trigger deep sleep from a task with an internal stack. This matters for exactly the battery-powered agent devices that PSRAM attracts. In practice it means your architecture should keep one small internal-RAM task responsible for power management, while the memory-hungry buffers and model artifacts live in external RAM. Get that split right and PSRAM is close to transparent; get it wrong and the failure appears only in the field, at sleep time. Source: Support for External RAM, ESP-IDF Programming Guide
Optional advanced placements exist for squeezing more out of the chip: configuration items allow .bss and .noinit segments in external memory, and even flash instruction and read-only-data sections to run from PSRAM. Treat those as deliberate optimizations with their own caveats, not defaults for a first project. Source: Support for External RAM, ESP-IDF Programming Guide
Our assessment is that PSRAM configuration belongs in the first project checklist for any ESP32-S3 build that handles audio, vision or agent workloads, because retrofitting it after out-of-memory failures means re-debugging allocation behavior you already shipped. Identify the module, match Quad or Octal, pick an allocation mode deliberately, and keep deep-sleep triggers on internal stacks. Our ESP32 AI voice agent guide shows the class of workload where this headroom becomes the constraint.
Check the module shielding for the family name and version code, then match them against Espressif's table. An empty result means the module has no PSRAM to configure; WROOM-2 modules are always Octal SPI. Source: Troubleshooting, Arduino ESP32 documentation
The most common cause is the wrong interface setting. A board with Quad or Octal PSRAM uploaded with default settings reboots in a loop; set Tools, PSRAM to QSPI PSRAM or OPI PSRAM to match the module. Source: Troubleshooting, Arduino ESP32 documentation
Espressif documents up to 32 MB of virtual addresses for external PSRAM, mapped into the address space and usable, with restrictions, like internal data RAM. The actual size depends on the chip on your module. Source: Support for External RAM, ESP-IDF Programming Guide
Yes. The default CONFIG_SPIRAM_USE option makes PSRAM allocatable through malloc, with a threshold option steering small allocations to internal RAM and a reserved internal pool protecting DMA-capable buffers. Source: Support for External RAM, ESP-IDF Programming Guide
Not safely. Espressif says the standard deep-sleep start call logs an error and proceeds, and the device will likely crash; use the checking variant and trigger deep sleep from a task whose stack is in internal RAM. Source: Support for External RAM, ESP-IDF Programming Guide
Ready to take the first step towards unlocking opportunities, realizing goals, and embracing innovation? We're here and eager to connect.