|
1 | | -Filename | Description |
2 | | ---------------------|---------------------------------------------------------------------------------------------------------------------------- |
3 | | -banlist.dat | stores the IPs/Subnets of banned nodes |
4 | | -bitcoin.conf | contains configuration settings for bitcoind or bitcoin-qt |
5 | | -bitcoind.pid | stores the process id of bitcoind while running |
6 | | -blocks/blk000??.dat | block data (custom, 128 MiB per file); since 0.8.0 |
7 | | -blocks/rev000??.dat | block undo data (custom); since 0.8.0 (format changed since pre-0.8) |
8 | | -blocks/index/* | block index (LevelDB); since 0.8.0 |
9 | | -chainstate/* | blockchain state database (LevelDB); since 0.8.0 |
10 | | -database/* | BDB database environment; only used for wallet since 0.8.0; moved to wallets/ directory on new installs since 0.16.0 |
11 | | -db.log | wallet database log file; moved to wallets/ directory on new installs since 0.16.0 |
12 | | -debug.log | contains debug information and general logging generated by bitcoind or bitcoin-qt |
13 | | -fee_estimates.dat | stores statistics used to estimate minimum transaction fees and priorities required for confirmation; since 0.10.0 |
14 | | -indexes/txindex/* | optional transaction index database (LevelDB); since 0.17.0 |
15 | | -mempool.dat | dump of the mempool's transactions; since 0.14.0 |
16 | | -peers.dat | peer IP address database (custom format); since 0.7.0 |
17 | | -wallet.dat | personal wallet (BDB) with keys and transactions; moved to wallets/ directory on new installs since 0.16.0 |
18 | | -wallets/database/* | BDB database environment; used for wallets since 0.16.0 |
19 | | -wallets/db.log | wallet database log file; since 0.16.0 |
20 | | -wallets/wallet.dat | personal wallet (BDB) with keys and transactions; since 0.16.0 |
21 | | -.cookie | session RPC authentication cookie (written at start when cookie authentication is used, deleted on shutdown): since 0.12.0 |
22 | | -onion_private_key | cached Tor hidden service private key for `-listenonion`: since 0.12.0 |
23 | | -guisettings.ini.bak | backup of former GUI settings after `-resetguisettings` is used |
24 | | - |
25 | | -Only used in pre-0.8.0 |
26 | | ---------------------- |
27 | | -* blktree/*; block chain index (LevelDB); since pre-0.8, replaced by blocks/index/* in 0.8.0 |
28 | | -* coins/*; unspent transaction output database (LevelDB); since pre-0.8, replaced by chainstate/* in 0.8.0 |
29 | | - |
30 | | -Only used before 0.8.0 |
31 | | ---------------------- |
32 | | -* blkindex.dat: block chain index database (BDB); replaced by {chainstate/*,blocks/index/*,blocks/rev000??.dat} in 0.8.0 |
33 | | -* blk000?.dat: block data (custom, 2 GiB per file); replaced by blocks/blk000??.dat in 0.8.0 |
34 | | - |
35 | | -Only used before 0.7.0 |
36 | | ---------------------- |
37 | | -* addr.dat: peer IP address database (BDB); replaced by peers.dat in 0.7.0 |
| 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 | +- [GUI settings](#gui-settings) |
| 12 | + |
| 13 | +- [Legacy subdirectories and files](#legacy-subdirectories-and-files) |
| 14 | + |
| 15 | +- [Notes](#notes) |
| 16 | + |
| 17 | +## Data directory location |
| 18 | + |
| 19 | +The data directory is the default location where the Bitcoin Core files are stored. |
| 20 | + |
| 21 | +1. The default data directory paths for supported platforms are: |
| 22 | + |
| 23 | +Platform | Data directory path |
| 24 | +---------|-------------------- |
| 25 | +Linux | `$HOME/.bitcoin/` |
| 26 | +macOS | `$HOME/Library/Application Support/Bitcoin/` |
| 27 | +Windows | `%APPDATA%\Bitcoin\` <sup>[\[1\]](#note1)</sup> |
| 28 | + |
| 29 | +2. The non-default data directory path can be specified by `-datadir` option. |
| 30 | + |
| 31 | +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: |
| 32 | + |
| 33 | +Chain option | Data directory path |
| 34 | +--------------------|-------------------- |
| 35 | +no option (mainnet) | *path_to_datadir*`/` |
| 36 | +`-testnet` | *path_to_datadir*`/testnet3/` |
| 37 | +`-regtest` | *path_to_datadir*`/regtest/` |
| 38 | + |
| 39 | +## Data directory layout |
| 40 | + |
| 41 | +Subdirectory | File(s) | Description |
| 42 | +-------------------|-----------------------|------------ |
| 43 | +`blocks/` | | Blocks directory; can be specified by `-blocksdir` option (except for `blocks/index/`) |
| 44 | +`blocks/index/` | LevelDB database | Block index; `-blocksdir` option does not affect this path |
| 45 | +`blocks/` | `blkNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Actual Bitcoin blocks (in network format, dumped in raw on disk, 128 MiB per file) |
| 46 | +`blocks/` | `revNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Block undo data (custom format) |
| 47 | +`chainstate/` | LevelDB database | Blockchain state (a compact representation of all currently unspent transaction outputs and some metadata about the transactions they are from) |
| 48 | +`indexes/txindex/` | LevelDB database | Transaction index; *optional*, used if `-txindex=1` |
| 49 | +`wallets/` | | [Contains wallets](#multi-wallet-environment); can be specified by `-walletdir` option; if `wallets/` subdirectory does not exist, a wallet resides in the data directory |
| 50 | +`./` | `banlist.dat` | Stores the IPs/subnets of banned nodes |
| 51 | +`./` | `bitcoin.conf` | Contains [configuration settings](bitcoin-conf.md) for `bitcoind` or `bitcoin-qt`; can be specified by `-conf` option |
| 52 | +`./` | `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 |
| 53 | +`./` | `debug.log` | Contains debug information and general logging generated by `bitcoind` or `bitcoin-qt`; can be specified by `-debuglogfile` option |
| 54 | +`./` | `fee_estimates.dat` | Stores statistics used to estimate minimum transaction fees and priorities required for confirmation |
| 55 | +`./` | `guisettings.ini.bak` | Backup of former [GUI settings](#gui-settings) after `-resetguisettings` option is used |
| 56 | +`./` | `mempool.dat` | Dump of the mempool's transactions |
| 57 | +`./` | `onion_private_key` | Cached Tor hidden service private key for `-listenonion` option |
| 58 | +`./` | `peers.dat` | Peer IP address database (custom format) |
| 59 | +`./` | `.cookie` | Session RPC authentication cookie; if used, created at start and deleted on shutdown; can be specified by `-rpccookiefile` option |
| 60 | +`./` | `.lock` | Data directory lock file |
| 61 | + |
| 62 | +## Multi-wallet environment |
| 63 | + |
| 64 | +Wallets are Berkeley DB (BDB) databases: |
| 65 | + |
| 66 | +Subdirectory | File(s) | Description |
| 67 | +-------------|-------------------|------------ |
| 68 | +`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` |
| 69 | +`./` | `db.log` | BDB error file |
| 70 | +`./` | `wallet.dat` | Personal wallet (BDB) with keys and transactions |
| 71 | +`./` | `.walletlock` | Wallet lock file |
| 72 | + |
| 73 | +1. Each user-defined wallet named "wallet_name" resides in `wallets/wallet_name/` subdirectory. |
| 74 | + |
| 75 | +2. The default (unnamed) wallet resides in `wallets/` subdirectory; if the latter does not exist, the wallet resides in the data directory. |
| 76 | + |
| 77 | +3. A wallet database path can be specified by `-wallet` option. |
| 78 | + |
| 79 | +## GUI settings |
| 80 | + |
| 81 | +`bitcoin-qt` uses [`QSettings`](https://doc.qt.io/qt-5/qsettings.html) class; this implies platform-specific [locations where application settings are stored](https://doc.qt.io/qt-5/qsettings.html#locations-where-application-settings-are-stored). |
| 82 | + |
| 83 | +## Legacy subdirectories and files |
| 84 | + |
| 85 | +These subdirectories and files are no longer used by the Bitcoin Core: |
| 86 | + |
| 87 | +Path | Description | Repository notes |
| 88 | +---------------|-------------|----------------- |
| 89 | +`blktree/` | Blockchain index; replaced by `blocks/index/` in [0.8.0](https://github.com/bitcoin/bitcoin/blob/master/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) |
| 90 | +`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) |
| 91 | +`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) |
| 92 | +`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) |
| 93 | +`addr.dat` | Peer IP address BDB database; replaced by `peers.dat` in [0.7.0](https://github.com/bitcoin/bitcoin/blob/master/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) |
| 94 | + |
| 95 | +## Notes |
| 96 | + |
| 97 | +<a name="note1">1</a>. The `/` (slash, U+002F) is used as the platform-independent path component separator in this paper. |
| 98 | + |
| 99 | +<a name="note2">2</a>. `NNNNN` matches `[0-9]{5}` regex. |
| 100 | + |
0 commit comments