Mac OSX
Mac installation Mac OS X Yosemite 10.10.x
Last updated
Mac installation Mac OS X Yosemite 10.10.x
Last updated
Go to the and verify you have made a secure connection to the server.
Bitcoin Core initial synchronization will take time and download a lot of data. You should make sure that you have enough bandwidth and storage for the block chain size (7GB). If you have a good Internet connection, you can help strengthen the network by keeping your PC running with Bitcoin Core and port 8333 open.
After downloading the file to your Downloads folder (/Users/<YOUR USER NAME>/Downloads), run it by double-clicking its icon. OS X will open a Finder window for you to drag Bitcoin Core to your Applications folder.
Window to install
Bitcoin Core GUI
The first time running Bitcoin Core, Max OS X will ask you to confirm that you want to run it:
Mac OS X File Security Dialog
You will be prompted to choose a directory to store the Bitcoin block chain and your wallet. Unless you have a separate partition or drive you want to use, click Ok to use the default.
Bitcoin Core Welcome
Bitcoin Core GUI will begin to download the block chain. This step will take at least several days, and it may take much more time on a slow Internet connection or with a slow computer. During the download, Bitcoin Core will use a significant part of your connection bandwidth. You can stop Bitcoin Core at any time by closing it; it will resume from the point where it stopped the next time you start it.
Bitcoin Core Initial Block Download
After download is complete, you may use Bitcoin Core as your wallet or you can just let it run to help support the Bitcoin network.
Optional: Start Your Node At Login
Starting your node automatically each time you login to your computer makes it easy for you to contribute to the network. The easiest way to do this is to tell Bitcoin Core GUI to start at login.
While running Bitcoin Core GUI, open the Bitcoin Core menu and choose Preferences. On the Main tab, click Start Bitcoin on system login. Click the Ok button to save the new settings.
The next time you login to your desktop, Bitcoin Core GUI will be automatically started minimized in the task bar.
Bitcoin Core Daemon
The Bitcoin Core daemon (bitcoind) is not included in the .dmg file you may have downloaded to install Bitcoin-QT. Bitcoind, along with its support binaries, is instead included in the OS X .tar.gz file listed on the official Bitcoin Core download page. To download this file using Terminal, execute the following command:
Copy
Optional: Verify the release signatures
Copy
Copy
Even earlier releases were signed by Gavin Andresen’s key. His primary key’s fingerprint is:
Copy
You should verify these keys belong to their owners using the web of trust or other trustworthy means. Then use PGP to verify the signature on the release signatures file. Finally, use PGP or another utility to compute the SHA256 hash of the archive you downloaded, and ensure the computed hash matches the hash listed in the verified release signatures file.
Extract bitcoind and its support binaries from the archive we just downloaded by running this command in Terminal:
Copy
Now we’ll move the executables into your default path to make running and stopping bitcoind easier. To move the executables, run these commands (note that we have to use sudo to perform these commands since we are modifying directories owned by root):
Copy
To clean up the directory we’ve been working in, run:
Copy
You should now be able to start up your full node by running bitcoind -daemon in any Terminal window. If you need to stop bitcoind for any reason, the command is bitcoin-cli stop
Optional: Start Your Node At Login
Starting your node automatically each time you login to your computer makes it easy for you to contribute to the network. The easiest way to do this is to tell Bitcoin Core Daemon to start at login. In OS X, the way to start background programs at login is using a Launch Agent. Here is how to install a Launch Agent for Bitcoin Core daemon on your machine:
Copy
The next time you login to your desktop, Bitcoin Core daemon will be automatically started.
If you are running an older version, shut it down. Wait until it has completely shut down (which might take a few minutes for older versions), then run the installer (on Windows) or just copy over /Applications/Bitcoin-Qt (on Mac) or bitcoind/bitcoin-qt (on Linux).
The blockchain and wallet files in the data directory are compatible between versions so there is no requirement to make any changes to the data directory when upgrading. Occasionally the format of those files changes, but the new Bitcoin Core version will include code that automatically upgrades the files to the new format so no manual intervention is required.
Sometimes upgrade of the blockchain data files from very old versions to the new versions is not supported. In those cases it may be necessary to redownload the blockchain. Check the release notes of the new version if you are planning to upgrade from a very old version.
Sometimes downgrade is not possible because of changes to the data files. Again, check the release notes for the new version if you are planning to downgrade.
If you want to support the Bitcoin network, you must allow inbound connections.
When Bitcoin Core starts, it establishes 10 outbound connections to other full nodes so it can download the latest blocks and transactions. If you just want to use your full node as a wallet, you don’t need more than these 10 connections—but if you want to support lightweight clients and other full nodes on the network, you must allow inbound connections.
Servers connected directly to the Internet usually don’t require any special configuration. You can use the testing instructions below to confirm your server-based node accepts inbound connections.
Home connections are usually filtered by a router or modem. Bitcoin Core will request your router automatically configure itself to allow inbound connections to Bitcoin’s port, port 8333. Unfortunately many routers don’t allow automatic configuration, so you must manually configure your router. You may also need to configure your firewall to allow inbound connections to port 8333. Please see the following subsections for details.
Testing Connections
For confirmation that you accept inbound connections, you can use Bitcoin Core. Bitcoin Core can’t tell you directly whether you allow inbound connections, but it can tell you whether or not you currently have any inbound connections. If your node has been online for at least 30 minutes, it should normally have inbound connections. If want to check your peer info using Bitcoin Core, choose the appropriate instructions below:
GUI Peer Info
In the bottom right corner of the Bitcoin Core GUI are several icons. If you hover over the signal strength icon, it will tell you how many connections you have. The icon won’t turn green until you have more than 10 active connections, which only happens if inbound connections are allowed.
For confirmation, you can go to the Help menu, choose Debug Window, and open the Information tab. In the Network section, it will tell you exactly how many inbound connections you have. If the number is greater than zero, then inbound connections are allowed.
Daemon Peer Info
Copy
Enabling Connections
Enabling inbound connections requires two steps, plus an extra third step for firewall users:
Giving your computer a static (unchanging) internal IP address by configuring the Dynamic Host Configuration Protocol (DHCP) on your router.
Forwarding inbound connections from the Internet through your router to your computer where Bitcoin Core can process them.
Configuring your firewall to allow inbound connections. This step mainly applies to Windows users, as Mac OS X and most Linuxes do not enable a firewall by default.
Configuring DHCP
In order for your router to direct incoming port 8333 connections to your computer, it needs to know your computer’s internal IP address. However, routers usually give computers dynamic IP addresses that change frequently, so we need to ensure your router always gives your computer the same internal IP address.
Start by logging into your router’s administration interface. Most routers can be configured using one of the following URLs, so keep clicking links until you find one that works. If none work, consult your router’s manual.
After logging in, you want to search your router’s menus for options related to DHCP, the Dynamic Host Configuration Protocol. These options may also be called Address Reservation. For example, the router page shown below calls the option we need “DHCP Reservation”:
In the reservation configuration, some routers will display a list of computers and devices currently connected to your network, and then let you select a device to make its current IP address permanent:
If that’s the case, find the computer running Bitcoin Core in the list, select it, and add it to the list of reserved addresses. Make a note of its current IP address—we’ll use the address in the next section.
Other routers require a more manual configuration. For these routers, you will need to look up the fixed address (MAC address) for your computer’s network card and add it to the list. This operation differs by operating system:
Windows 7 & 8: Press Win-R (Windows key plus the R key) to open the Run dialog. Type cmd to open the console. Type ipconfig /all and find the result that best matches your connection—usually a wireless connection. Look for a line that starts with “Physical Address” and contains a value like this:
Copy
Replace all the dashes with colons, so the address looks like this: 01:23:45:67:89:AB. Use that address in the instructions below.
Linux: open a terminal and type ifconfig. Find the result that best matches your connection—a result starting with wlan indicates a wireless connection. Find the field that starts with HWaddr and copy the immediately following field that looks like 01:23:45:67:89:ab. Use that value in the instructions below.
Mac OS X: open a terminal and type ifconfig. Find the result that best matches your connection—a result starting with en1 usually indicates a wireless connection. Find the field that starts with ether: and copy the immediately following field that looks like 01:23:45:67:89:ab. Use that value in the instructions below.
Once you have the MAC address, you can fill it into your router’s manual DHCP assignment table, as illustrated below. Also choose an IP address and make a note of it for the instructions in the next subsection. After entering this information, click the Add or Save button.
Then reboot your computer to ensure it gets assigned the address you selected and proceed to the Port Forwarding instructions below.
Port Forwarding
For this step, you need to know the local IP address of the computer running Bitcoin Core. You should have this information from configuring the DHCP assignment table in the subsection above.
The port forwarding settings should allow you to map an external port on your router to the “internal port” of a device on your network as shown in the screenshot below.
Both the external port and the internal port should be 8333 for Bitcoin. (You may also want to map port 18333 for Bitcoin’s testnet, although this guide does not cover using testnet.) Make sure the IP address you enter is the same one you configured in the previous subsection.
If you still can’t connect and you use a firewall, you probably need to change your firewall settings. See the Firewall section below.
Firewall Configuration
Firewalls block inbound connections. To use Bitcoin, you need to configure your computer’s firewall to allow connections to port 8333. This is usually as easy as starting your firewall configuration software and defining a new rule to allow inbound connections to port 8333. For additional information for Windows, see the links below:
This section contains advice about how to change your Bitcoin Core configuration to adapt it to your needs.
There are two ways to change your configuration. The first is to start Bitcoin Core with the options you want. For example, if you want to limit it to using one CPU core for signature verification, you can start Bitcoin Core like this:
Copy
Once you’ve decided you like an option, you can add it to the Bitcoin Core configuration file. You can find that file in the following directories:
Windows: %APPDATA%\Bitcoin\
OSX: $HOME/Library/Application Support/Bitcoin/
Linux: $HOME/.bitcoin/
To add an option to the configuration file, just remove its leading dash. You may also need to remove any quotation marks you used in your shell. For example, the -par option seen above would look like this in the configuration file:
Copy
Reduce Storage
It is possible to configure your node to run in pruned mode in order to reduce storage requirements. This can reduce the disk usage from over 350GB to around 7GB.
Running a node in pruned mode is incompatible with -txindex and -rescan. It also disables the RPC importwallet. Two RPCs that are available and potentially helpful, however, are importprunedfunds and removeprunedfunds.
To enable block pruning set prune=N on the command line or in bitcoin.conf, where N is the number of MiB to allot for raw block and undo data.
A value of 0 disables pruning. The minimal value above 0 is 550. Your wallet is as secure with high values as it is with low ones. Higher values merely ensure that your node will not shut down upon blockchain reorganizations of more than 2 days - which are unlikely to happen in practice. In future releases, a higher value may also help the network as a whole because stored blocks could be served to other nodes.
Reduce Traffic
Some node operators need to deal with bandwidth caps imposed by their ISPs.
By default, Bitcoin Core allows up to 125 connections to different peers, 10 of which are outbound. You can therefore have at most 115 inbound connections.
The default settings can result in relatively significant traffic consumption.
Ways to reduce traffic:
Maximum Upload Targets
Copy
A major component of the traffic is caused by serving historic blocks to other nodes during the initial blocks download phase (syncing up a new node). This option can be specified in MiB per day and is turned off by default. This is not a hard limit; only a threshold to minimize the outbound traffic. When the limit is about to be reached, the uploaded data is cut by no longer serving historic blocks (blocks older than one week). Keep in mind that new nodes require other nodes that are willing to serve historic blocks. The recommended minimum is 144 blocks per day (max. 144MiB per day)
Disable listening
Copy
Disabling listening will result in fewer nodes connected (remember the maximum of 10 outbound peers). Fewer nodes will result in less traffic usage as you are relaying blocks and transactions to fewer nodes.
Reduce maximum connections
Copy
Reducing the maximum connected nodes to a minimum could be desirable if traffic limits are tiny. Keep in mind that Bitcoin’s trustless model works best if you are connected to a handful of nodes.
Blocks-only mode
Copy
Causes your node to stop requesting and relaying transactions unless they are part of a block and also disables listening as described above.
This reduces your node’s bandwidth to the absolute minimum necessary to stay synchronized with the network, about 150 megabytes incoming data per day and about 1 megabyte of outgoing data per day, but it does mean that your node won’t see incoming transactions until they’ve received at least one confirmation.
You will still be able to send transactions from the built-in wallet or from peers you’ve whitelisted using the -whitelist parameter.
Choosing to start Bitcoin Core at login
You have now completed installing Bitcoin Core. If you have any questions, please ask in one of Bitcoin’s many , such as , , or the IRC chatroom on Freenode.
To support the Bitcoin network, you also need to allow incoming connections. Please read the section for details.
If you know how to use PGP, you should also click the Verify Release Signatures link on the download page to download a signed list of SHA256 file hashes. The 0.11 and later releases are signed by with the fingerprint:
Earlier releases were signed by . That key’s fingerprint is:
You have now completed installing Bitcoin Core. If you have any questions, please ask in one of Bitcoin’s many , such as , , or the IRC chatroom on Freenode.
To support the Bitcoin network, you also need to allow incoming connections. Please read the section for details.
The BitNodes project provides an online tool to let you test whether your node accepts inbound connections. Before using BitNodes, you must first ensure that your node is fully synced with the block chain. Once you’ve done so, start Bitcoin Core (either the GUI or the daemon), wait 10 minutes, and then . The tool will attempt to guess your IP address—if the address is wrong (or blank), you will need to enter your address manually.
Bitnodes Tool
After you press Check Node, the tool will inform you whether your port is open (green box) or not open (red box). If you get the green box, you don’t need to do anything—you accept inbound connections. If you get the red box, please read the subsection.
Active connections
Debug window with inbound connections
If you don’t have inbound connections, please read the instructions for
The command will tell you how many connections you have. If you have more than 10 connections, inbound connections are allowed. For example:
For confirmation, you can use the command to get information about all of your peers. Each peer’s details will include an inbound field set to true if the connection is inbound. If you have any inbound connections, then inbound connections are allowed.
If you don’t have inbound connections, please read instructions for
If Bitcoin Core can’t automatically configure your router to open port 8333, you will need to manually configure your router. We’ve tried to make the following instructions generic enough to cover most router models; if you need specific help with your router, please ask for help on a tech support site such as .
(some Linksys/Cisco models)
(some D-Link/Netgear models)
(some Belkin/SMC models)
(some US Robotics models)
(some Apple models)
Upon connecting, you will probably be prompted for a username and password. If you configured a password, enter it now. If not, the provides a database of known default username and password pairs.
DHCP reservation button
Easy DHCP reservation
Manual DHCP reservation
Login to your router using the same steps described near the top of the . Look for an option called Port Forwarding, Port Assignment, or anything with “Port” in its name. On some routers, this option is buried in an Applications & Gaming menu.
Port forwarding
After filling in the details for the mapping, save the entry. You should not need to restart anything. Start Bitcoin Core (if you haven’t already) and follow the instructions to test your connection.
If something else went wrong, it’s probably a problem with your router configuration. Re-read the instructions above to see if you missed anything, search the web for help with “port forwarding”, and ask for help on sites like .
We can’t provide direct support, but if you see a way to improve these instructions, please
Mac OS X comes with its firewall disabled by default, but if you have enabled it, see the section Allowing Specific Applications from the
Ubuntu also comes with its firewall disabled by default, but if you have enabled it, see the for information about adding port forwarding rules.
Once you have allowed inbound connections to port 8333, start Bitcoin Core (if you haven’t already) and follow the instructions to test your connection.
If something else went wrong re-read the DHCP, port forwarding, and firewall instructions above to see if you missed anything, search the web for help with “port forwarding” and “opening firewall ports”, and ask for help on sites like .
We can’t provide direct support, but if you see a way to improve these instructions, please
A user-friendly configuration file generator is If you have any questions about configuring Bitcoin Core, please stop by one of our or .
