Bitcoincore
Bitcoincore pruning
Bitcoin Core can delete eligible old block and undo files to reduce local storage. Choose manual or automatic pruning after checking whether your setup needs the full transaction index.
- Automatic mode
-
Bitcoin Core v31.0:
-prune=<n>sets a target in MiB for block and undo files, withnat least 550. - Manual mode
-
Bitcoin Core v31.0:
-prune=1enables manual pruning throughpruneblockchain. It does not set a 1 MiB storage target. - Index compatibility
-
Bitcoin Core v31.0 cannot combine enabled pruning with
-txindex, which maintains a full transaction index. Pruning also fails at startup if -txospenderindex, the transaction output spender index, is enabled. - Restoring full history
- In Bitcoin Core v31.0, returning to unpruned operation after deleting history requires downloading the entire blockchain again.
Choose the mode before starting
The full transaction index supports
getrawtransaction
lookups. If your workload needs that index, keep pruning disabled with
-prune=0
, the default.
Use
bitcoin.conf
for persistent custom settings, or pass the pruning option when launching
bitcoind
. Automatic mode allows deletion once files qualify; manual mode requires an explicit pruning request.
The pruning storage target applies to block and undo files, so budget additional space for other node data.
Read the pruning state
The getblockchaininfo RPC reports the running node's pruning state in Bitcoin Core v31.0.
-
prunedreports whether the node runs in pruning mode. A value oftruealone does not establish that deletion has occurred. -
When the node runs in pruning mode,
automatic_pruningdistinguishes automatic mode from manual mode. -
pruneheightalso appears in pruning mode. It marks the first unpruned height, or 0 if the node has not pruned any blocks.
The
size_on_disk
field estimates the disk space occupied by block and undo files.
Request manual deletion only when ready
The
pruneblockchain
RPC requires pruning at startup and remains available in automatic mode. It deletes eligible block and undo data using a requested height or timestamp.
The RPC takes a nonnegative argument. Values up to
1000000000
identify block heights, and larger values represent Unix timestamps. A timestamp request targets blocks whose times are at least two hours older than the supplied timestamp.
A request fails if the chain is too short for pruning, the requested height exceeds its tip, or the timestamp lookup finds no matching block. The node also retains required recent blocks, which can keep deletion short of the requested boundary.
The RPC returns the highest pruned block height, or -1 if the node has not pruned any blocks. That boundary can include earlier pruning, so the response alone does not prove that this call deleted more files.
Example: Check manual mode before deleting history
Hypothetical setup: an operator has stopped a Bitcoin Core v31.0 node that retains its full block history. The previous setup used
-txindex=1
, and the proposed automatic pruning target is 2747 MiB.
A dependency check confirms that no application needs the full transaction index. Both choices therefore disable that index before enabling pruning; retaining it would make either pruning mode incompatible.
| Startup choice | Expected pruning state | Deletion and stopping point |
|---|---|---|
bitcoind -txindex=0 -prune=1
|
pruned: true
and
automatic_pruning: false
|
No automatic deletion. Stop before issuing
pruneblockchain
to preserve the existing history.
|
bitcoind -txindex=0 -prune=2747
|
pruned: true
and
automatic_pruning: true
|
Automatic pruning can delete eligible history. Returning to unpruned operation after deletion requires downloading the full blockchain again. |
The operator chooses manual mode for the first check. In this hypothetical result,
getblockchaininfo
also returns
pruneheight: 0
, confirming that the node has not pruned any blocks. The operator can return to
-prune=0
at this point with history intact. Manual mode supplies no automatic storage cap.