doc: explain swapping in `reduce-memory.md`
What the developer wrote
Authored by Lőrinc
doc: explain swapping in `reduce-memory.md`
Document what swapping is and why it can severely degrade `bitcoind` performance.
What changed, and why it matters
This commit only adds documentation to a user guide about how operating-system swapping can slow down Bitcoin Core. It is a non-code change with no security implications.
No action needed; this is a documentation-only change.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff adds a new ‘Swapping’ section to doc/reduce-memory.md explaining OS memory pressure, swap thrashing, and how to lower memory-related parameters such as -dbcache, -maxmempool, -maxconnections, and -blocksonly. No source code is modified.
Changed components
doc/reduce-memory.mdInspect captured patch +9 / −0
diff --git a/doc/reduce-memory.md b/doc/reduce-memory.md
index cac5dc98..e3ab3bad 100644
--- a/doc/reduce-memory.md
+++ b/doc/reduce-memory.md
@@ -2,6 +2,15 @@
There are a few parameters that can be dialed down to reduce the memory usage of `bitcoind`. This can be useful on embedded systems or small VPSes.
+## Swapping
+
+When the operating system is under memory pressure, it may swap memory pages from RAM to disk.
+If this becomes continuous ("thrashing"), `bitcoind` can slow to a crawl, especially during initial sync or reindex.
+
+If you see sustained swap I/O while `bitcoind` runs, restart with a lower `-dbcache`.
+If needed, also reduce `-maxmempool`, `-maxconnections`, or use `-blocksonly`.
+Bitcoin Core may warn at startup when `-dbcache` looks too large for the detected system memory.
+
## In-memory caches
The size of some in-memory caches can be reduced. As caches trade off memory usage for performance, reducing these will usually have a negative effect on performance.
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.