Skip to main content
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 SystemDefault 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

​
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
​
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
​
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
​
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" admin@example.com

​
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