Bitcoin Core file system
Contents
Data directory location
The data directory is the default location where the Bitcoin Core files are stored.
- The default data directory paths for supported platforms are:
| Platform | Data directory path |
|---|---|
| Linux | $HOME/.bitcoin/ |
| macOS | $HOME/Library/Application Support/Bitcoin/ |
| Windows | %LOCALAPPDATA%\Bitcoin\ [1] |
-
A custom data directory path can be specified with the
-datadiroption. -
All content of the data directory, except for
bitcoin.conffile, is chain-specific. This means the actual data directory paths for non-mainnet cases differ:
| Chain option | Data directory path |
|---|---|
-chain=main (default) | path_to_datadir/ |
-chain=test or -testnet | path_to_datadir/testnet3/ |
-chain=testnet4 or -testnet4 | path_to_datadir/testnet4/ |
-chain=signet or -signet | path_to_datadir/signet/ |
-chain=regtest or -regtest | path_to_datadir/regtest/ |
Data directory layout
| Subdirectory | File(s) | Description |
|---|---|---|
blocks/ | Blocks directory; can be specified by -blocksdir option (except for blocks/index/) | |
blocks/index/ | LevelDB database | Block index; -blocksdir option does not affect this path |
blocks/ | blkNNNNN.dat[2] | Actual Bitcoin blocks (dumped in network format, 128 MiB per file) |
blocks/ | revNNNNN.dat[2] | Block undo data (custom format) |
blocks/ | xor.dat | Rolling XOR pattern for block and undo data files |
chainstate/ | LevelDB database | Blockchain state (a compact representation of all currently unspent transaction outputs (UTXOs) and metadata about the transactions they are from) |
indexes/txindex/ | LevelDB database | Transaction index; optional, used if -txindex=1 |
indexes/blockfilter/basic/db/ | LevelDB database | Blockfilter index LevelDB database for the basic filtertype; optional, used if -blockfilterindex=basic |
indexes/blockfilter/basic/ | fltrNNNNN.dat[2] | Blockfilter index filters for the basic filtertype; optional, used if -blockfilterindex=basic |
indexes/coinstats/db/ | LevelDB database | Coinstats index; optional, used if -coinstatsindex=1 |
wallets/ | Contains wallets; can be specified by -walletdir option; if wallets/ subdirectory does not exist, wallets reside in the data directory | |
./ | anchors.dat | Anchor IP address database, created on shutdown and deleted at startup. Anchors are last known outgoing block-relay-only peers that are tried to re-connect to on startup |
./ | banlist.json | Stores the addresses/subnets of banned nodes. |
./ | bitcoin.conf | User-defined configuration settings for bitcoind or bitcoin-qt. File is not written to by the software and must be created manually. Path can be specified by -conf option |
./ | bitcoind.pid | Stores the process ID (PID) of bitcoind or bitcoin-qt while running; created at start and deleted on shutdown; can be specified by -pid option |
./ | debug.log | Contains debug information and general logging generated by bitcoind or bitcoin-qt; can be specified by -debuglogfile option |
./ | fee_estimates.dat | Stores statistics used to estimate minimum transaction fees required for confirmation |
./ | guisettings.ini.bak | Backup of former GUI settings after -resetguisettings option is used |
./ | ip_asn.map | IP addresses to Autonomous System Numbers (ASNs) mapping used for bucketing of the peers; path can be specified with the -asmap option |
./ | mempool.dat | Dump of the mempool's transactions |
./ | onion_v3_private_key | Cached Tor onion service private key for -listenonion option |
./ | i2p_private_key | Private key that corresponds to our I2P address. When -i2psam= is specified the contents of this file is used to identify ourselves for making outgoing connections to I2P peers and possibly accepting incoming ones. Automatically generated if it does not exist. |
./ | peers.dat | Peer IP address database (custom format) |
./ | settings.json | Read-write settings set through GUI or RPC interfaces, augmenting manual settings from bitcoin.conf. File is created automatically if read-write settings storage is not disabled with -nosettings option. Path can be specified with -settings option |
./ | .cookie | Session RPC authentication cookie; if used, created at start and deleted on shutdown; can be specified by -rpccookiefile option |
./ | .lock | Data directory lock file |
Multi-wallet environment
Wallets are Berkeley DB (BDB) or SQLite databases.
-
Each user-defined wallet named "wallet_name" resides in the
wallets/wallet_name/subdirectory. -
The default (unnamed) wallet resides in
wallets/subdirectory; if the latter does not exist, the wallet resides in the data directory. -
A wallet database path can be specified with the
-walletoption. -
wallet.datfiles must not be shared across different node instances, as that can result in key-reuse and double-spends due the lack of synchronization between instances. -
Any copy or backup of the wallet should be done through a
backupwalletcall in order to update and lock the wallet, preventing any file corruption caused by updates during the copy.
Berkeley DB database based wallets
| Subdirectory | File(s) | Description |
|---|---|---|
database/ | BDB logging files | Part of BDB environment; created at start and deleted on shutdown; a user must keep it as safe as personal wallet wallet.dat |
./ | db.log | BDB error file |
./ | wallet.dat | Personal wallet (a BDB database) with keys and transactions |
./ | .walletlock | BDB wallet lock file |
SQLite database based wallets
| Subdirectory | File | Description |
|---|---|---|
./ | wallet.dat | Personal wallet (a SQLite database) with keys and transactions |
./ | wallet.dat-journal | SQLite Rollback Journal file for wallet.dat. Usually created at start and deleted on shutdown. A user must keep it as safe as the wallet.dat file. |
GUI settings
bitcoin-qt uses QSettings class; this implies platform-specific locations where application settings are stored.
Legacy subdirectories and files
These subdirectories and files are no longer used by Bitcoin Core:
| Path | Description | Repository notes |
|---|---|---|
banlist.dat | Stores the addresses/subnets of banned nodes; superseded by banlist.json in 22.0 and completely ignored in 23.0 | PR #20966, PR #22570 |
blktree/ | Blockchain index; replaced by blocks/index/ in 0.8.0 | PR #2231, 8fdc94cc |
coins/ | Unspent transaction output database; replaced by chainstate/ in 0.8.0 | PR #2231, 8fdc94cc |
blkindex.dat | Blockchain index BDB database; replaced by {chainstate/, blocks/index/, blocks/revNNNNN.dat[2]} in 0.8.0 | PR #1677 |
blk000?.dat | Block data (custom format, 2 GiB per file); replaced by blocks/blkNNNNN.dat[2] in 0.8.0 | PR #1677 |
addr.dat | Peer IP address BDB database; replaced by peers.dat in 0.7.0 | PR #1198, 928d3a01 |
onion_private_key | Cached Tor onion service private key for -listenonion option. Was used for Tor v2 services; replaced by onion_v3_private_key in 0.21.0 | PR #19954 |
Notes
1. The / (slash, U+002F) is used as the platform-independent path component separator in this document.
2. NNNNN matches [0-9]{5} regex.