-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathregtest.html
More file actions
168 lines (153 loc) · 15.3 KB
/
Copy pathregtest.html
File metadata and controls
168 lines (153 loc) · 15.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
<!DOCTYPE html>
<!-- SPDX-License-Identifier: AGPL-3.0-or-later | TestnetHub © 2026 Tech1k -->
<html lang="en" data-theme="dark">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Bitcoin regtest: your private testnet · TestnetHub</title>
<meta name="description" content="Run bitcoind in regtest mode for a private local chain where you mine blocks on demand and confirmations are instant, ideal for automated tests.">
<link rel="canonical" href="https://testnethub.com/regtest">
<meta name="robots" content="index, follow">
<meta name="referrer" content="no-referrer">
<meta name="theme-color" content="#14161b">
<meta name="author" content="Tech1k">
<meta property="og:type" content="article">
<meta property="og:site_name" content="TestnetHub">
<meta property="og:title" content="Bitcoin regtest: your private testnet · TestnetHub">
<meta property="og:description" content="Run bitcoind in regtest mode for a private local chain where you mine blocks on demand and confirmations are instant, ideal for automated tests.">
<meta property="og:url" content="https://testnethub.com/regtest">
<meta property="og:image" content="https://testnethub.com/assets/og.png?v=2">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="TestnetHub: learn crypto with fake coins and real protocols">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Bitcoin regtest: your private testnet · TestnetHub">
<meta name="twitter:description" content="Run bitcoind in regtest mode for a private local chain where you mine blocks on demand and confirmations are instant, ideal for automated tests.">
<meta name="twitter:image" content="https://testnethub.com/assets/og.png?v=2">
<link rel="icon" href="/favicon.svg" type="image/svg+xml">
<link rel="apple-touch-icon" href="/assets/icon-192.png">
<link rel="manifest" href="/manifest.webmanifest">
<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; manifest-src 'self'; object-src 'none'; base-uri 'none'; form-action 'none'">
<script src="/assets/theme-init.js?v=1"></script>
<link rel="stylesheet" href="/assets/style.css?v=5">
<script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://testnethub.com/#org","name":"TestnetHub","url":"https://testnethub.com/","logo":"https://testnethub.com/favicon.svg"},{"@type":"WebSite","@id":"https://testnethub.com/#website","name":"TestnetHub","url":"https://testnethub.com/","publisher":{"@id":"https://testnethub.com/#org"},"description":"Learn the Bitcoin, Litecoin, and Monero testnets with free coins and real protocols."}]}</script>
<script type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://testnethub.com/"},{"@type":"ListItem","position":2,"name":"Guides","item":"https://testnethub.com/guides"},{"@type":"ListItem","position":3,"name":"Bitcoin regtest","item":"https://testnethub.com/regtest"}]}</script>
<script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"Bitcoin regtest","description":"Run bitcoind in regtest mode for a private local chain where you mine blocks on demand and confirmations are instant, ideal for automated tests.","inLanguage":"en","isPartOf":{"@id":"https://testnethub.com/#website"},"publisher":{"@id":"https://testnethub.com/#org"},"author":{"@id":"https://testnethub.com/#org"},"dateModified":"2026-08-07","mainEntityOfPage":"https://testnethub.com/regtest"}</script>
</head>
<body>
<a class="skip-link" href="#main">Skip to content</a>
<span id="copy-status" role="status" class="visually-hidden"></span>
<nav class="navbar">
<a href="/" class="brand" aria-label="TestnetHub home">
<svg class="brand-logo" viewBox="0 0 64 64" width="26" height="26" aria-hidden="true"><rect class="mark-bg" width="64" height="64" rx="14"/><g stroke="currentColor" stroke-width="3.4" stroke-linecap="round"><line x1="32" y1="32" x2="19" y2="19"/><line x1="32" y1="32" x2="45" y2="19"/><line x1="32" y1="32" x2="19" y2="45"/><line x1="32" y1="32" x2="45" y2="45"/></g><g fill="currentColor"><circle cx="19" cy="19" r="5"/><circle cx="45" cy="19" r="5"/><circle cx="19" cy="45" r="5"/><circle cx="45" cy="45" r="5"/><circle cx="32" cy="32" r="6.5"/></g></svg>
<span class="brand-name">Testnet<b>Hub</b></span>
</a>
<input type="checkbox" class="menu-toggle" id="menu-toggle" aria-label="Open the navigation menu" aria-controls="nav-links">
<label for="menu-toggle" class="hamburger"><div></div><div></div><div></div></label>
<div class="nav-links" id="nav-links">
<a href="/">Home</a>
<a href="/testnets">Testnets</a>
<a href="/guides">Guides</a>
<a href="/tools">Tools</a>
<a href="/status">Status</a>
<a href="/donate">Donate</a>
<button class="theme-toggle" id="theme-toggle" type="button" aria-label="Toggle light / dark theme" title="Toggle theme"><svg class="ico ico-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg><svg class="ico ico-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg></button>
</div>
</nav>
<main id="main" class="filled" tabindex="-1">
<p class="crumb"><a href="/guides">Guides</a> / Bitcoin regtest</p>
<div class="card hero">
<div class="card-body">
<h1><span class="grad">Bitcoin regtest, your private testnet</span></h1>
<p class="lede">regtest is a local chain you fully control, where you mine blocks on demand and confirmations happen instantly, ideal for automated tests and fast iteration.</p>
</div>
</div>
<div class="toc">
<p class="toc-title">On this page</p>
<ul>
<li><a href="#what">What regtest is</a></li>
<li><a href="#start">Start it</a></li>
<li><a href="#wallet">Make a wallet and address</a></li>
<li><a href="#mine">Mine some blocks</a></li>
<li><a href="#send">Send and confirm instantly</a></li>
<li><a href="#when">When to use it</a></li>
</ul>
</div>
<div class="card"><div class="card-body prose">
<h2 id="what">What regtest is <a class="anchor" tabindex="-1" href="#what" aria-hidden="true">#</a></h2>
<p><strong>regtest</strong> (regression test mode) is a private Bitcoin chain that runs entirely on your own machine. You are the only miner, blocks get made only when you ask for them, and nothing ever touches the internet. That means no waiting for a block, no competing for coins, and no shared state with anyone else.</p>
<p>The coins on regtest are even more worthless than <a href="/testnets">public testnet</a> coins, because they never leave your computer. You mine them yourself in a fresh chain that starts from block zero, and you can throw the whole thing away and start over whenever you like.</p>
<p>Public testnet is a <em>shared</em> network with real timing: blocks arrive roughly every few minutes, other people are using it, and you claim coins from a <a href="/faucet">faucet</a>. regtest is the opposite. It is solo, and time moves only when you say so. Use public testnet when you want realistic conditions, and regtest when you want speed and full control.</p>
<h2 id="start">Start it <a class="anchor" tabindex="-1" href="#start" aria-hidden="true">#</a></h2>
<p>You need Bitcoin Core installed (the same <code>bitcoind</code> and <code>bitcoin-cli</code> you would use for a <a href="/bitcoin">Bitcoin testnet</a> node). Launch the daemon in regtest mode, then check that it is running:</p>
<div class="codeblock"><button class="copybtn code-copy" type="button" data-copy-code aria-label="Copy code to clipboard">Copy</button><pre><code>bitcoind -regtest -daemon
bitcoin-cli -regtest getblockchaininfo</code></pre></div>
<p>The <code>getblockchaininfo</code> output shows <code>"chain": "regtest"</code> and a block height of <code>0</code> on a fresh chain. Every command below passes <code>-regtest</code> so it talks to this private chain and not to mainnet or testnet.</p>
<h2 id="wallet">Make a wallet and address <a class="anchor" tabindex="-1" href="#wallet" aria-hidden="true">#</a></h2>
<p>Create a wallet, then generate an address to mine to and receive with:</p>
<div class="codeblock"><button class="copybtn code-copy" type="button" data-copy-code aria-label="Copy code to clipboard">Copy</button><pre><code>bitcoin-cli -regtest createwallet "dev"
ADDR=$(bitcoin-cli -regtest getnewaddress)</code></pre></div>
<p>The <code>$ADDR</code> shell variable now holds a fresh regtest address you can reuse in the next commands. This is throwaway, but the habit still holds: never put a real seed phrase or a real private key anywhere near any testnet or regtest wallet.</p>
<h2 id="mine">Mine some blocks <a class="anchor" tabindex="-1" href="#mine" aria-hidden="true">#</a></h2>
<p>Here is the one rule that trips people up. When you mine a block, its reward (the <strong>coinbase</strong>) is not spendable right away. Bitcoin makes coinbase coins wait for <strong>100 more blocks</strong> to mature before you can spend them. This is the coinbase maturity rule, and regtest enforces it just like mainnet.</p>
<p>So to end up with spendable coins, mine <strong>101</strong> blocks. The reward from block 1 matures once block 101 exists:</p>
<div class="codeblock"><button class="copybtn code-copy" type="button" data-copy-code aria-label="Copy code to clipboard">Copy</button><pre><code>bitcoin-cli -regtest generatetoaddress 101 "$ADDR"
bitcoin-cli -regtest getbalance</code></pre></div>
<p><code>generatetoaddress</code> mines the requested number of blocks instantly and sends each reward to <code>$ADDR</code>. After 101 blocks, <code>getbalance</code> reports a spendable balance (the first block's reward, now mature). Mine more any time you want more coins.</p>
<h2 id="send">Send and confirm instantly <a class="anchor" tabindex="-1" href="#send" aria-hidden="true">#</a></h2>
<p>Sending works exactly like it does on any Bitcoin chain, except <em>you</em> produce the confirmation. Send the coins, then mine a single block to confirm the transaction:</p>
<div class="codeblock"><button class="copybtn code-copy" type="button" data-copy-code aria-label="Copy code to clipboard">Copy</button><pre><code>bitcoin-cli -regtest sendtoaddress <dest> 1.0
bitcoin-cli -regtest generatetoaddress 1 "$ADDR"</code></pre></div>
<p>Replace <code><dest></code> with any regtest address. After <code>sendtoaddress</code>, the transaction sits in your mempool with zero <a href="/confirmations">confirmations</a>. The moment you mine one block it lands on the chain with one confirmation. No waiting, no fee guessing, no <a href="/debug-stuck-tx">stuck transactions</a>. That instant, on-demand confirmation is what makes regtest ideal for automated tests: your test controls precisely when a transaction confirms.</p>
<h2 id="when">When to use it <a class="anchor" tabindex="-1" href="#when" aria-hidden="true">#</a></h2>
<p>regtest and public testnet solve different problems. Reach for regtest when you want speed and repeatability, and for public testnet when you want realistic timing or something other people can see.</p>
<div class="table-wrap"><table>
<thead><tr><th scope="col"> </th><th scope="col">regtest</th><th scope="col">Public testnet</th></tr></thead>
<tbody>
<tr><th scope="row">Timing</th><td>Instant, blocks on demand</td><td>Realistic, blocks every few minutes</td></tr>
<tr><th scope="row">Participants</th><td>Solo, only you</td><td>Shared with everyone</td></tr>
<tr><th scope="row">Getting coins</th><td>Mine your own</td><td>Claim from a <a href="/faucet">faucet</a></td></tr>
<tr><th scope="row">Best for</th><td>Automated tests, fast iteration</td><td>Sharing, demos, realistic conditions</td></tr>
<tr><th scope="row">Explorer</th><td>Local only</td><td><a href="/explorer">TestnetScan</a></td></tr>
</tbody>
</table></div>
<p>A common workflow is to build and test against regtest first, then run the same code against public testnet before you ever touch mainnet. If you want a public, shared network instead of a private one, spin up a node: the walkthrough in <a href="/run-node">run a Litecoin testnet node</a> applies to <code>bitcoind -testnet4</code> too. For a wider look at building, read <a href="/bitcoin">Bitcoin testnet</a> and <a href="/mining">mining</a>. The companion code examples repo has a full regtest walkthrough you can copy and run: <a class="ext" href="https://github.com/Tech1k/testnet-examples" target="_blank" rel="noopener">testnet-examples</a>.</p>
</div></div>
<div class="warnbox">
<span class="wb-ico" aria-hidden="true">⚠️</span>
<div class="wb-body">
<h3>Testnet coins are fake money</h3>
<ul>
<li>They have no market value, so never buy or sell them.</li>
<li>Never use a real seed phrase or import a real wallet on testnet.</li>
<li>Never send mainnet BTC, LTC, or XMR to a testnet address.</li>
</ul>
</div>
</div>
<div class="pagenav">
<a href="/build-app"><div class="pn-dir">← Previous</div><div class="pn-t">Build a testnet app</div></a>
<a class="pn-next" href="/guides"><div class="pn-dir">Next →</div><div class="pn-t">All guides</div></a>
</div>
</main>
<footer>
<div class="foot-inner">
<a class="ext" href="https://cypherfaucet.com" target="_blank" rel="noopener">Faucet</a>
<a class="ext" href="https://testnetpool.com" target="_blank" rel="noopener">Pool</a>
<a class="ext" href="https://testnetwallet.net" target="_blank" rel="noopener">Wallet</a>
<a class="ext" href="https://testnetscan.com" target="_blank" rel="noopener">Explorer</a>
<a class="ext" href="https://testnetswap.com" target="_blank" rel="noopener">Swap</a>
<a href="/guides">Guides</a>
<a href="/status">Status</a>
<a href="/donate">Donate</a>
<span class="faint">·</span>
<span>Part of the <a class="ext" href="https://tech1k.com" target="_blank" rel="noopener">Tech1k</a> testnet ecosystem</span>
<span class="faint">·</span>
<a class="ext" href="https://github.com/Tech1k/testnethub.com" target="_blank" rel="noopener">Source</a>
<a class="ext" href="https://github.com/Tech1k/testnethub.com/blob/HEAD/LICENSE" target="_blank" rel="noopener">Code AGPL-3.0</a>
<a class="ext" href="https://github.com/Tech1k/testnethub.com/blob/HEAD/LICENSE-CONTENT" target="_blank" rel="noopener">Content CC-BY-SA-4.0</a>
<span class="faint">· testnet only · coins have no value</span>
</div>
</footer>
<script src="/assets/copy.js?v=2"></script>
</body>
</html>