Beginner’s Guide to Setting up a Tezos Node with Docker, Opam and Source with Common Problems and Solutions

Adam Shinder
8 min readNov 5, 2020

The following tutorials are for Mac specifically. I’m using MacOS Catalina Version 10.15.5. All of these tutorials are explained step by step so they’re great for beginners. Docker is the easiest way to install and begin running the node, but if issues with the node occur, there is no way to debug it. The node takes about 50 GB of storage space.

Method 1: Docker: Step by Step

  1. Install Docker if you don’t have it already:
  2. Once downloaded, or if you already had it, make sure it’s open and running.
  3. If you’d like to run a Carthagenet (test network) node, type in wherever it says (Personally, I’ll be running my node on the test net)
  4. To run a mainnet node, type into your terminal:

a.wget -O

b.chmod +x

At this point, if you have the error message, zsh: command not found: wget. Then install Homebrew and then the command, brew install wget and continue.

5. To now run the node, copy and paste in the following:

./ start

6. Your node should now be running on the Tezos network! To check, type in:

./ node status

7. For more commands, type in:

./ — help

8. To prove it’s running, type in the command, ./ head to see the most recently baked block. It should look like this:

9. To stop the node, type in:

./ stop

10. Type in ./ node status to prove it’s stopped. It will show the following:

./ node status

Method 2: Setting up a node on the Tezos Mainnet from Opam: Step by Step

We’ll be doing this entirely from the terminal of your computer so there’s no need to download any additional software.

  1. First we’ll be installing Opam. Open the terminal on your computer and copy and paste the following into the terminal:

a. sh <(curl -sL

b. As shown below, it will ask where it wants to install. I created a new folder called “new_teznode”. When prompted to create the folder, type “y” and it will be installed.

NOTE: You can also install Opam in the main directory, by simply pressing space when prompted to where it should be installed. This will install Opam globally.

c. Type in the command line,opam init — bare

If opam init -bare didn’t work, check out solution 4 on the bottom of the article.

2. Now that you created a new folder called, “new_teznode”, type “ls” into your terminal and you’ll see all the available directories. You’ll see “new_teznode” so now type in “cd new_teznode”. This changes the directory to new_teznode and now we’ll start working within this directory. As you can see, once I changed directories, I am now working within the new_teznode directory.

NOTE: If Opam is installed globally, you can run these commands in any directory.

3. Get the line from this website to install Rust: It should look like this, curl — proto ‘=https’ — tlsv1.2 -sSf | sh but it changes based on the system you’re running on. Copy and paste this into the terminal. When prompted, press 1 to continue with the installation.

4. Then, type source $HOME/.cargo/env

5. In the new_teznode, (or any directory in the terminal if Opam is installed globally) copy and paste each line, press enter and go to the next one.

a. rustup set profile minimal

b. rustup toolchain install 1.39.0

c. rustup default 1.39.0

d. source $HOME/.cargo/env

6. The following is more configuration for Opam and Tezos compatibility.

a.opam switch create for_tezos 4.09.1

b. eval $(opam env)

c. opam install depext //When prompted to continue, write yes (“Y”)

d. opam depext tezos //Should say, “#All required OS packages found.”

e. opam install tezos

A list of actions will pop-up, this is what’s about to be installed. Do you want to continue? [Y/n] Write “Y”. Wait for it to process. There will be 189 actions to be installed and another 378 afterward, so it will take about 30 minutes, depending on your wifi connection.

7. To upgrade Opam and make sure everything is up to date, type the following commands:

a. opam update

b. opam depext

c. opam upgrade

If you receive this error message: “The following packages are not being upgraded because the new versions conflict with other installed packages” Don’t worry, the node should still operate fine without the most recent versions.

Congratulations! You just finished setting up your node on the Tezos blockchain! To start running your node, check out the section on the bottom, “Running the Node”.

Method 3: Setting up a node on the Tezos Mainnet from the source: Step by Step

The following tutorial is used for setting up the node from the source code.

  1. Before building the node from the source, you must have Opam installed, either globally or within the directory.

a. sh <(curl -sL

b. opam init — bare

c. opam switch create for_tezos 4.09.1

d. eval $(opam env)

e. opam install depext //When prompted to continue, write yes (“Y”)

f. opam depext tezos //Should say, “#All required OS packages found.”

g. opam install tezos

2. We’re now going to retrieve the source code. Copy and Paste the following one by one into the command line.

a. git clone //this pulls the node from the source on Gitlab

b. cd tezos //You should now be operating in the tezos directory.

c. git checkout latest-release

d. opam init — bare//Answer N then Y to the questions, as shown

e. make build-deps //There’s 228 installations, this will take a few minutes

f. eval $(opam env)

g. make

h. export PATH=~/tezos:$PATH

i. source ./src/bin_client/


You’re done! Your node is all set up. To run the node, check out the next section titled, “Running the Node”.

Running the Node

The following steps are for running the node only if you set up your node with methods 2 or 3, and not via Docker.

Now, we need to create an identity the node will work under and your node will start running.

1. Type in the following: ./tezos-node identity generate

2. To start the node, copy and paste the following:

tezos-node run — rpc-addr localhost

Boom! You’re now running your very own node on the Tezos blockchain! Congratulations!! It’s going to connect to the blockchain and start backing up all the information from the ledger. If you want to install snapshots or to learn more about them, check out:

Here’s a few basic commands that are important to know to control your node:

  1. To stop the node — tezos-node stop

2. To re-configure from the Mainnet to Carthagenet or vice-versa — ./tezos-node config init — network carthagenet //type mainnet if you want mainnet

3. To exit a current running process, Ctrl + C

4. To check if your node is in sync with the blockchain — ./tezos-client bootstrapped // if “Bootstrapped” is returned, it’s in sync

Thank you for reading and I hope you were able to set-up and properly configure your node! If you have any questions, please feel free to reach me on Twitter @AdShinder, or Telegram or LinkedIn at Adam Shinder.

More Resources:

Issues I faced the first time, and how I solved them:


  1. If you see the “Too few connections” it means the port you chose, currently localhost, is running somewhere else. To see a list of the ports you have running, type, ps aux | grep ./tezos

To kill the process, sudo kill -9 <INSERT PORT>

2. If you want to delete the Tezos node, there are restrictions to deleting the file. Type in rm -rf filename to delete the file and override the restriction. If that doesn’t work, You can delete it by removing restrictions with chmod 777 filename. This gives everyone read, write, and execute privileges. Then, do rm -rf filename.

3. If you’re having trouble with the “opam: command not found”,first make sure you have a file called opam within the directory. If that’s there, check that the PATH is correct and you’re working in the right terminal. If all this is good, then reinstall opam in an empty directory and once done, type, “opam update; opam install opam-devel”. Then, “opam init” and it should start running again.

4. Add opam to your current PATH with the following.

vim ~/.zshrc //if you’re using zsh

vim ~/.bash_profile //if you’re using bash

This opens up your configuration window.

Now, edit the document and anywhere you want, type the following:

export PATH=$HOME/new_teznode:$PATH

This adds opam to your current path

Now, save and close the configuration file and restart your terminal. Go into the new_teznode directory and continue.

If you want more information on the PATH variable, check this out:

I’m currently an Intern at Tezos Israel. Check out our Medium for more information on Tezos at Tezos Israel and follow us on Twitter @TezosIsrael.