bitcoin.conf Configuration File

Complete guide to Bitcoin Core configuration file format, syntax, and common options

The bitcoin.conf configuration file is used by bitcoind, bitcoin-qt, and bitcoin-cli to control Bitcoin Core’s behavior.

Configuration File Location

By default, bitcoin.conf is located in the Bitcoin data directory:

Operating System	Default Path
Linux	~/.bitcoin/bitcoin.conf
macOS	~/Library/Application Support/Bitcoin/bitcoin.conf
Windows	%LOCALAPPDATA%\Bitcoin\bitcoin.conf

You can specify a custom location using the -conf command-line option:

bitcoind -conf=/path/to/custom/bitcoin.conf

File Format

The configuration file is a plain text file with option=value entries, one per line.

Basic Syntax

# This is a comment
option=value
anotheroption=anothervalue

Leading and trailing whitespaces are removed. An option must be specified without the leading - used in command-line arguments.

Comments

Comments start with # and extend to the end of the line:

# Full line comment (preferred)
txindex=1  # Inline comment after option

Network-Specific Options

Options can be specified for specific networks using section headers or prefixes:

# Using section headers
[main]
rpcport=8332

[test]
rpcport=18332

[regtest]
rpcport=18443

# Using prefixes
regtest.maxmempool=100

The testnet section header is [test], not [testnet]. For testnet4, use [testnet4].

Network-specific options take precedence over non-network specific options. If multiple values for the same option are found with the same precedence, the first one is chosen.

Negated Options

Most options can be negated using the no prefix:

# Disable transaction index
notxindex=1

# Disable DNS lookups
nodns=1

Common Configuration Options

Core Options

datadir · string

Specify the data directory path. Default varies by platform.

datadir=/mnt/bitcoin

conf · string

Specify path to an additional configuration file. Relative paths are prefixed by datadir location.

# Not available in bitcoin.conf, command-line only

includeconf · string

Include additional configuration file. Can be used multiple times. Relative to datadir.

includeconf=rpc.conf
includeconf=network.conf

pid · string

Specify PID file location. Default: bitcoind.pid

pid=/var/run/bitcoind.pid

Chain and Database Options

chain · string · default: "main"

Use a specific chain: main, test, testnet4, signet, or regtest

chain=regtest

testnet · boolean · default: "0"

Use the test network (testnet3)

testnet=1

regtest · boolean · default: "0"

Enter regression test mode

regtest=1

dbcache · number · default: "450"

Maximum database cache size in MiB. Minimum 4, default 450.

dbcache=4096

prune · number · default: "0"

Reduce storage by pruning old blocks. Specify target size in MiB. 0=disable, 1=enable with 550 MiB minimum.

prune=10000

txindex · boolean · default: "0"

Maintain a full transaction index for the getrawtransaction RPC

txindex=1

blocksdir · string

Specify directory to hold blocks subdirectory. Default: <datadir>

blocksdir=/mnt/storage/blocks

RPC Server Options

server · boolean · default: "0"

Accept command line and JSON-RPC commands

server=1

rpcuser · string

Username for JSON-RPC connections

rpcuser=bitcoinrpc

rpcpassword · string

Password for JSON-RPC connections

rpcpassword=your-secure-password-here

rpcauth · string

Username and HMAC-SHA-256 hashed password. Format: <USERNAME>:<SALT>$<HASH>

rpcauth=alice:e3c4f2a7$0f2d98a1b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0

rpcport · number

Listen for JSON-RPC connections on this port. Default: 8332 (mainnet), 18332 (testnet3), 18443 (regtest)

rpcport=8332

rpcbind · string · default: "127.0.0.1"

Bind to given address to listen for JSON-RPC connections. Use [host]:port notation for IPv6.

rpcbind=127.0.0.1:8332
rpcbind=[::1]:8332

rpcallowip · string · default: "127.0.0.1"

Allow JSON-RPC connections from specified source. Can specify IP, network/netmask, or network/CIDR.

rpcallowip=127.0.0.1
rpcallowip=192.168.1.0/24

Do not expose the RPC server to untrusted networks such as the public internet!

rest · boolean · default: "0"

Accept public REST requests

rest=1

Network Options

listen · boolean · default: "1"

Accept connections from outside

listen=1

port · number

Listen for connections on this port. Default: 8333 (mainnet), 18333 (testnet3), 18444 (regtest)

port=8333

bind · string

Bind to given address and always listen on it. Use [host]:port notation for IPv6.

bind=0.0.0.0:8333
bind=[::]:8333

maxconnections · number · default: "125"

Maintain at most this many connections to peers

maxconnections=200

addnode · string

Add a node to connect to and attempt to keep the connection open. Can be specified multiple times.

addnode=69.164.218.197
addnode=10.0.0.2:8333

connect · string

Connect only to the specified node(s). Can be specified multiple times.

connect=192.168.1.100

proxy · string

Connect through SOCKS5 proxy

proxy=127.0.0.1:9050

onion · string

Use separate SOCKS5 proxy to reach peers via Tor onion services

onion=127.0.0.1:9050

Mempool Options

maxmempool · number · default: "300"

Keep the transaction memory pool below this many megabytes

maxmempool=500

mempoolexpiry · number · default: "336"

Do not keep transactions in the mempool longer than this many hours

mempoolexpiry=72

persistmempool · boolean · default: "1"

Save the mempool on shutdown and load on restart

persistmempool=1

Advanced Options

Mining and Block Creation

blockmaxweight · number · default: "3996000"

Set maximum BIP141 block weight

blockmaxweight=4000000

blockmintxfee · number · default: "0.00001000"

Set lowest fee rate (in BTC/kvB) for transactions to be included in block creation

blockmintxfee=0.00001

Transaction Relay

minrelaytxfee · number · default: "0.00001000"

Fees (in BTC/kvB) smaller than this are considered zero fee for relaying and mining

minrelaytxfee=0.00001

blocksonly · boolean · default: "0"

Reject transactions from network peers. Automatic broadcast is disabled.

blocksonly=1

datacarrier · boolean · default: "1"

Relay and mine data carrier transactions

datacarrier=1

ZeroMQ Notifications

zmqpubhashblock · string

Enable publish hash block in specified address

zmqpubhashblock=tcp://127.0.0.1:28332

zmqpubhashtx · string

Enable publish hash transaction in specified address

zmqpubhashtx=tcp://127.0.0.1:28332

zmqpubrawblock · string

Enable publish raw block in specified address

zmqpubrawblock=tcp://127.0.0.1:28332

zmqpubrawtx · string

Enable publish raw transaction in specified address

zmqpubrawtx=tcp://127.0.0.1:28332

Notification Commands

blocknotify · string

Execute command when the best block changes. %s in cmd is replaced by block hash.

blocknotify=/usr/local/bin/notify-block.sh %s

alertnotify · string

Execute command when an alert is raised. %s in cmd is replaced by message.

alertnotify=echo %s | mail -s "Bitcoin Alert" [e-mail]

Configuration Precedence

Settings are applied in the following order (later overrides earlier):

1. bitcoin.conf file
2. settings.json file (dynamic settings from GUI/RPC)
3. Command-line options

The settings.json file contains dynamic settings set by Bitcoin Core GUI and RPCs at runtime, and augments or replaces static settings in bitcoin.conf.

Example Configurations

Minimal RPC Configuration

# Enable RPC server
server=1

# RPC authentication
rpcuser=bitcoinrpc
rpcpassword=change_this_password

# Listen only on localhost
rpcbind=127.0.0.1:8332
rpcallowip=127.0.0.1

Pruned Node Configuration

# Reduce storage requirements
prune=10000

# Disable transaction index (incompatible with pruning)
txindex=0

# Limit mempool size
maxmempool=100

Full Archival Node

# Maximum cache for better performance
dbcache=4096

# Full transaction index
txindex=1

# Large mempool
maxmempool=500

# Listen for connections
listen=1

Testnet Configuration

# Use testnet
testnet=1

# Enable RPC
server=1
rpcuser=testuser
rpcpassword=testpass

Validation and Debugging

To check which settings are in use:

1. Check debug.log output for configuration values
2. Unrecognized options appear as warnings in debug.log
3. Use bitcoin-cli getinfo to verify runtime settings

Users should never make configuration changes they do not understand. Always be cautious of accepting configuration changes from untrusted sources.

See Also

• Command-Line Options - All available command-line arguments
• Data Directory Structure - File and directory layout