This section provides an overview of the structure of Bitcoin Core directories. The data directory is the location where Bitcoin's data files are stored, including the wallet data file. Understanding the data structure of Bitcoin Core is useful if you wish to send a friend (or the future yourself) the entire blockchain, avoiding a hefty download.
- The data directory is the default location where the Bitcoin Core files are stored.
- The default data directory paths for Linux-based systems is:
$HOME/.bitcoin/, i.e. for example/home/username/.bitcoin/ - A custom data directory path can be specified via the
-datadiroption - All content of the data directory, except for
bitcoin.conffile, is chain-specific - 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 -datadirshould be your FASTEST storage
-blocksdirshould be your LARGEST storage
-walletdirshould be your most SECURE storage
An overview of these table is in also available in the Bitcoin Core documentation files.md.
| Subdirectory | File(s) | Safely deleted | Description |
|---|---|---|---|
./ |
bitcoin.conf |
No | 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. It may contain your IP or hidden service address, paths on your filesystem, and RPC credentials. |
./ |
settings.json |
No | Read-write settings set through GUI or RPC interfaces, augmenting manual settings with a similar nature of bitcoin.conf. File is created automatically if read-write settings storage is not disabled with -nosettings option. Path can be specified with -settings option |
./ |
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 |
./ |
peers.dat |
Yes | It contains addresses and connection statistics of peers, but does not contain any personally identifiable data |
./ |
banlist.json |
- | Stores the addresses/subnets of banned nodes |
./ |
onion_v3_private_key |
Keep secret | Contains your hidden service key if you are running Bitcoin Core through a Tor connection |
./ |
debug.log |
Yes | Contains debug information and general logging generated by bitcoind or bitcoin-qt; can be specified by -debuglogfile option. It may contain IP addresses and transaction ID's |
./ |
mempool.dat |
- | Dump of the mempool's transactions |
./ |
fee_estimates.dat |
Yes | Stores statistics used to estimate minimum transaction fees required for confirmation. It may contain information pertaining to your wallet |
./ |
wallet.dat |
Make backup | Contains the wallet files with private keys and UTXOs |
./ |
db.log |
Yes | Database log of access to wallet |
./ |
.cookie |
Keep secret | Contains temporary RPC credentials in situations where you haven't specified an explicit username & password. |
./ |
.lock |
Yes | Data directory lock file |
~/blocks |
- |
- | Contain information pertaining only to the public blockchain. This directory ist cross-platform, i.e. it can be copied between different installation. It can be specified by -blocksdir option (except for blocks/index/) |
~/blocks |
blk###.dat |
- | Actual Bitcoin raw blocks (dumped in network format, 128 MB per file) |
~/blocks |
rev###.dat |
- | Block undo data (custom format), contains a list of spent UTXOs for each block |
~/blocks |
xor.dat |
- | Rolling XOR pattern for block and undo data files |
~/blocks/index |
LevelDB database | - | Contain information pertaining only to the public blockchain. Block index; -blocksdir option does not affect this path |
~/chainstate |
LevelDB database | - | Blockchain state (a compact representation of all currently unspent transaction outputs - UTXOs - and metadata about the transactions they are from). It contains information pertaining only to the public blockchain. This directory ist cross-platform, i.e. it can be copied between different installation |
~/indexes/txindex |
LevelDB database | - | Transaction index; optional, used if -txindex=1 |
~/wallets |
- |
Keep secret | Contains wallets; path can be specified by -walletdir option; if wallets/ subdirectory does not exist, wallets reside in the data directory, i.e. the default location where the Bitcoin Core files are stored $HOME/.bitcoin/ |
~/database/folder |
- |
- | This should only exist when bitcoin-qt is currently running. It contains information (BDB state) relating to your wallet |
- The default data directory paths for Linux-based systems is:
$HOME/.bitcoin/, i.e. for example/home/username/.bitcoin/bitcoin.conf - The configuration file is used by
bitcoind,bitcoin-qtandbitcoin-cli - Changes to the configuration file while
bitcoindorbitcoin-qtis running only take effect after restarting. - Options specified in the configuration file can be overridden by options in the
settings.jsonfile and by options specified on the command line. - The
settings.jsonfile contains dynamic settings that are set by the Bitcoin Core GUI and RPCs at runtime, and augment or replace the static settings specified in thebitcoin.conffile. - Command line options also augment or replace
bitcoin.confoptions, and can be useful for scripting and debugging - It is possible to see which setting values are in use by checking
debug.logoutput. Any unrecognized options that are found inbitcoin.confalso show up as warnings indebug.logoutput.
The database files in the "blocks" and "chainstate" directories are cross-platform, and can be copied between different installations. These files, known collectively as a node's "block database", represent all of the information downloaded by a node during the syncing process. In other words, if you copy installation A's block database into installation B, installation B will then have the same syncing percentage as installation A. This is usually far faster than doing the normal initial sync over again. However, when you copy someone's database in this way, you are trusting them absolutely. Bitcoin Core treats its block database files as 100% accurate and trustworthy, whereas during the normal initial sync it treats each block offered by a peer as invalid until proven otherwise. If an attacker is able to modify your block database files, then they can do all sorts of evil things which could cause you to lose bitcoins. Therefore, you should only copy block databases from Bitcoin installations under your personal control, and only over a secure connection.
Each node has a unique block database, and all of the files are highly connected. So if you copy just a few files from one installation's "blocks" or "chainstate" directories into another installation, this will almost certainly cause the second node to crash or get stuck at some random point in the future. If you want to copy a block database from one installation to another, you have to delete the old database and copy all of the files at once. Both nodes have to be shut down while copying.
Only the file with the highest number in the "blocks" directory is ever written to. The earlier files will never change. Also, when these blk*.dat files are accessed, they are usually accessed in a highly sequential manner. Therefore, it's possible to symlink the "blocks" directory or some subset of the blk*.dat files individually onto a magnetic storage drive without much loss in performance (see Splitting the data directory), and if two installations start out with identical block databases (due to the copying described previously), subsequent runs of rsync will be very efficient