files.md
1 # Bitcoin Core file system 2 3 **Contents** 4 5 - [Data directory location](#data-directory-location) 6 7 - [Data directory layout](#data-directory-layout) 8 9 - [Multi-wallet environment](#multi-wallet-environment) 10 11 - [SQLite database based wallets](#sqlite-database-based-wallets) 12 13 - [GUI settings](#gui-settings) 14 15 - [Legacy subdirectories and files](#legacy-subdirectories-and-files) 16 17 - [Berkeley DB database based wallets](#berkeley-db-database-based-wallets) 18 19 - [Installed Files](#installed-files) 20 21 - [Filesystem recommendations](#filesystem-recommendations) 22 23 ## Data directory location 24 25 The data directory is the default location where the Bitcoin Core files are stored. 26 27 1. The default data directory paths for supported platforms are: 28 29 Platform | Data directory path 30 ---------|-------------------- 31 Linux | `$HOME/.bitcoin/` 32 macOS | `$HOME/Library/Application Support/Bitcoin/` 33 Windows | `%LOCALAPPDATA%\Bitcoin\` <sup>[\[1\]](#note1)</sup> 34 35 2. A custom data directory path can be specified with the `-datadir` option. 36 37 3. All content of the data directory, except for `bitcoin.conf` file, is chain-specific. This means the actual data directory paths for non-mainnet cases differ: 38 39 Chain option | Data directory path 40 ---------------------------------|------------------------------ 41 `-chain=main` (default) | *path_to_datadir*`/` 42 `-chain=test` or `-testnet` | *path_to_datadir*`/testnet3/` 43 `-chain=testnet4` or `-testnet4` | *path_to_datadir*`/testnet4/` 44 `-chain=signet` or `-signet` | *path_to_datadir*`/signet/` 45 `-chain=regtest` or `-regtest` | *path_to_datadir*`/regtest/` 46 47 ## Data directory layout 48 49 Subdirectory | File(s) | Description 50 -------------------|-----------------------|------------ 51 `blocks/` | | Blocks directory; can be specified by `-blocksdir` option (except for `blocks/index/`) 52 `blocks/index/` | LevelDB database | Block index; `-blocksdir` option does not affect this path 53 `blocks/` | `blkNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Actual Bitcoin blocks (dumped in network format, 128 MiB per file) 54 `blocks/` | `revNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Block undo data (custom format) 55 `blocks/` | `xor.dat` | Rolling XOR pattern for block and undo data files 56 `chainstate/` | LevelDB database | Blockchain state (a compact representation of all currently unspent transaction outputs (UTXOs) and metadata about the transactions they are from) 57 `indexes/txindex/` | LevelDB database | Transaction index; *optional*, used if `-txindex=1` 58 `indexes/txospenderindex/` | LevelDB database | Transaction spender index; *optional*, used if `-txospenderindex=1` 59 `indexes/blockfilter/basic/db/` | LevelDB database | Blockfilter index LevelDB database for the basic filtertype; *optional*, used if `-blockfilterindex=basic` 60 `indexes/blockfilter/basic/` | `fltrNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Blockfilter index filters for the basic filtertype; *optional*, used if `-blockfilterindex=basic` 61 `indexes/coinstatsindex/db/` | LevelDB database | Coinstats index; *optional*, used if `-coinstatsindex=1` 62 `wallets/` | | [Contains wallets](#multi-wallet-environment); can be specified by `-walletdir` option; if `wallets/` subdirectory does not exist, wallets reside in the [data directory](#data-directory-location) 63 `./` | `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 64 `./` | `banlist.json` | Stores the addresses/subnets of banned nodes. 65 `./` | `bitcoin.conf` | User-defined [configuration settings](bitcoin-conf.md) 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 66 `./` | `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 67 `./` | `debug.log` | Contains debug information and general logging generated by `bitcoind` or `bitcoin-qt`; can be specified by `-debuglogfile` option 68 `./` | `fee_estimates.dat` | Stores statistics used to estimate minimum transaction fees required for confirmation 69 `./` | `guisettings.ini.bak` | Backup of former [GUI settings](#gui-settings) after `-resetguisettings` option is used 70 `./` | `mempool.dat` | Dump of the mempool's transactions 71 `./` | `onion_v3_private_key` | Cached Tor onion service private key for `-listenonion` option 72 `./` | `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. 73 `./` | `peers.dat` | Peer IP address database (custom format) 74 `./` | `settings.json` | Read-write settings set through GUI or RPC interfaces, augmenting manual settings from [bitcoin.conf](bitcoin-conf.md). File is created automatically if read-write settings storage is not disabled with `-nosettings` option. Path can be specified with `-settings` option 75 `./` | `.cookie` | Session RPC authentication cookie; if used, created at start and deleted on shutdown; can be specified by `-rpccookiefile` option 76 `./` | `.lock` | Data directory lock file 77 78 ## Multi-wallet environment 79 80 Wallets are SQLite databases. 81 82 1. Each user-defined wallet named "wallet_name" resides in the `wallets/wallet_name/` subdirectory. 83 84 2. The default (unnamed) wallet resides in `wallets/` subdirectory; if the latter does not exist, the wallet resides in the data directory. 85 86 3. A wallet database path can be specified with the `-wallet` option. 87 88 4. `wallet.dat` files must not be shared across different node instances, as that can result in key-reuse and double-spends due to the lack of synchronization between instances. 89 90 5. Any copy or backup of the wallet should be done through a `backupwallet` call in order to update and lock the wallet, preventing any file corruption caused by updates during the copy. 91 92 93 ### SQLite database based wallets 94 95 Subdirectory | File | Description 96 -------------|----------------------|------------- 97 `./` | `wallet.dat` | Personal wallet (a SQLite database) with keys and transactions 98 `./` | `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. 99 100 101 ## GUI settings 102 103 `bitcoin-qt` uses [`QSettings`](https://doc.qt.io/qt-6/qsettings.html) class; this implies platform-specific [locations where application settings are stored](https://doc.qt.io/qt-6/qsettings.html#locations-where-application-settings-are-stored). 104 105 ## Legacy subdirectories and files 106 107 These subdirectories and files are no longer used by Bitcoin Core: 108 109 Path | Description | Repository notes 110 ---------------|-------------|----------------- 111 `banlist.dat` | Stores the addresses/subnets of banned nodes; superseded by `banlist.json` in 22.0 and completely ignored in 23.0 | [PR #20966](https://github.com/bitcoin/bitcoin/pull/20966), [PR #22570](https://github.com/bitcoin/bitcoin/pull/22570) 112 `blktree/` | Blockchain index; replaced by `blocks/index/` in [0.8.0](/doc/release-notes/release-notes-0.8.0.md#improvements) | [PR #2231](https://github.com/bitcoin/bitcoin/pull/2231), [`8fdc94cc`](https://github.com/bitcoin/bitcoin/commit/8fdc94cc8f0341e96b1edb3a5b56811c0b20bd15) 113 `coins/` | Unspent transaction output database; replaced by `chainstate/` in 0.8.0 | [PR #2231](https://github.com/bitcoin/bitcoin/pull/2231), [`8fdc94cc`](https://github.com/bitcoin/bitcoin/commit/8fdc94cc8f0341e96b1edb3a5b56811c0b20bd15) 114 `blkindex.dat` | Blockchain index BDB database; replaced by {`chainstate/`, `blocks/index/`, `blocks/revNNNNN.dat`<sup>[\[2\]](#note2)</sup>} in 0.8.0 | [PR #1677](https://github.com/bitcoin/bitcoin/pull/1677) 115 `blk000?.dat` | Block data (custom format, 2 GiB per file); replaced by `blocks/blkNNNNN.dat`<sup>[\[2\]](#note2)</sup> in 0.8.0 | [PR #1677](https://github.com/bitcoin/bitcoin/pull/1677) 116 `addr.dat` | Peer IP address BDB database; replaced by `peers.dat` in [0.7.0](/doc/release-notes/release-notes-0.7.0.md) | [PR #1198](https://github.com/bitcoin/bitcoin/pull/1198), [`928d3a01`](https://github.com/bitcoin/bitcoin/commit/928d3a011cc66c7f907c4d053f674ea77dc611cc) 117 `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](/doc/release-notes/release-notes-0.21.0.md) | [PR #19954](https://github.com/bitcoin/bitcoin/pull/19954) 118 119 ### Berkeley DB database based wallets 120 121 Subdirectory | File(s) | Description 122 -------------|-------------------|------------- 123 `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` 124 `./` | `db.log` | BDB error file 125 `./` | `wallet.dat` | Personal wallet (a BDB database) with keys and transactions 126 `./` | `.walletlock` | BDB wallet lock file 127 128 ### Notes 129 130 <a name="note1">1</a>. The `/` (slash, U+002F) is used as the platform-independent path component separator in this document. 131 132 <a name="note2">2</a>. `NNNNN` matches `[0-9]{5}` regex. 133 134 ## Installed Files 135 136 This table describes the files installed by Bitcoin Core across different platforms. 137 138 | **Path** | **Description** | 139 |------------------------------------------------------------|-----------------------------------------------------------------------------| 140 | [README.md](README.md) or [readme.txt](README_windows.txt) | Project information and instructions | 141 | bitcoin.conf | [Generated](../contrib/devtools/gen-bitcoin-conf.sh) configuration file | 142 | bin/bitcoin | Command-line tool for interacting with Bitcoin. Calls other binaries below. | 143 | bin/bitcoin-cli | Tool for making node and wallet RPC calls. | 144 | bin/bitcoin-qt | Bitcoin node and wallet GUI | 145 | bin/bitcoin-tx | Tool for creating and modifying transactions | 146 | bin/bitcoin-util | Miscellaneous utilities | 147 | bin/bitcoin-wallet | Bitcoin wallet tool | 148 | bin/bitcoind | Bitcoin node and wallet daemon | 149 | *lib/libbitcoinkernel.so* | Shared library containing core consensus and validation code | 150 | *lib/pkgconfig/libbitcoinkernel.pc* | Pkg-config metadata for linking to `libbitcoinkernel` | 151 | *libexec/bench_bitcoin* | Benchmarking tool for measuring node performance | 152 | *libexec/bitcoin-chainstate* | Tool to validate and connect blocks | 153 | libexec/bitcoin-gui | IPC-enabled alternative to `bitcoin-qt` | 154 | libexec/bitcoin-node | IPC-enabled alternative to `bitcoind` | 155 | libexec/test_bitcoin | Unit test binary | 156 | *libexec/test_bitcoin-qt* | GUI-specific unit tests | 157 | share/man/man1/ | Man pages for command-line tools like `bitcoin-cli`, `bitcoind`, and others | 158 | share/rpcauth/ | Documentation and scripts for RPC authentication setup | 159 160 ### Notes 161 162 - *Italicized* files are only installed in source builds if relevant CMake options are enabled. They are not included in binary releases. 163 - README and bitcoin.conf files are included in binary releases but not installed in source builds. 164 - On Windows, binaries have a `.exe` suffix (e.g., `bitcoin-cli.exe`). 165 166 ## Filesystem recommendations 167 168 When choosing a filesystem for the data directory (`datadir`) or blocks directory (`blocksdir`) on **macOS**,the `exFAT` filesystem should be avoided. 169 There have been multiple reports of database corruption and data loss when using this filesystem with Bitcoin Core, see [Issue #31454](https://github.com/bitcoin/bitcoin/issues/31454) for more details.