Linux Walkthrough


Hey Blockstackers!

If you’re using Linux to run Blockstack, this is a brief walk-through on how to get started. In this tutorial, I’m using Ubuntu 17.10. These instructions should work for most Debian-derived distros. Please let me know if there’s anything I can add to this to make it better!

1. Install Docker

If you alread have docker installed, then you can skip this step. Otherwise, you will need Docker installed for Blockstack to work. In Ubuntu, you can get it with:

    $ sudo apt-get install

If the above worked, then you’re done! If not, then please see my post further down.

If you are not using Ubuntu, you may need to explicitly start Docker, using something like this:

   $ sudo systemctl start docker

2. If you have installed blockstack before…

Check to see whether or not the folder ~/.blockstack exists already. This can be the case if you have already installed the browser, or installed the Blockstack CLI tools.

If you have a ~/.blockstack folder, you should move it out of the way:

    $ mv ~/.blockstack ~/.blockstack.bak.$(date +%s)

3. Run the Linux Launch Script

You can find the Linux install script here.

Once you download the script, you can fetch the Blockstack Docker images. Sample execution:

    $ cd ~/Downloads/
    $ bash ./ pull
    v0.20.1-browser: Pulling from blockstack/blockstack-core
    f6fa9a861b90: Already exists
    da7318603015: Already exists
    6a8bd10c9278: Already exists
    d5a40291440f: Already exists
    bbdd8a83c0f1: Already exists
    a3ed95caeb02: Already exists
    b03257f84b55: Already exists
    677219fe117b: Already exists
    d8f140b393f1: Already exists
    e9572be141d4: Already exists
    Digest: sha256:4ef81086bf62db0ed56b3dd2f4435ace61e88b2dbdc52ef58e843e48c0e6a397
    Status: Image is up to date for
    v0.20.1: Pulling from blockstack/blockstack-browser
    f6fa9a861b90: Already exists
    da7318603015: Already exists
    6a8bd10c9278: Already exists
    d5a40291440f: Already exists
    bbdd8a83c0f1: Already exists
    a3ed95caeb02: Already exists
    f0eed8246d65: Already exists
    ec6732fa14f2: Already exists
    3ee97b8d28a0: Already exists
    684cf17c3537: Already exists
    6b57ab123f0b: Already exists
    bba95de1cc22: Already exists
    835bd541d7d2: Already exists
    e61649b9671b: Already exists
    5ea4d49d4308: Already exists
    5260c951460d: Already exists
    681abe8d3c96: Already exists
    4784dd5ea250: Already exists
    Digest: sha256:3ba13666e5b790974e63e94dd6a3b9c16c474bba37a947aec47bf77c40477c0b
    Status: Image is up to date for

Finally, you can start the browser!

You will be prompted for a Blockstack Core password. This is different from the 12-word password that will be used to own your names. You will need to enter it each time you run start.

Sample execution:

    $ bash ./ start
    IMPORTANT: This will be used to encrypt information stored within the containers
               which may include private keys for your Blockstack wallet.
               It is important that you remember this password.
               This will be the password you use to "pair" your Blockstack Browser
               with your Blockstack core node.
               Legal characters:
                   letters (upper and lowercase), numbers, '_', and '-'
    Wallet does not exist yet. Setting up wallet
    Saving configuration to /root/.blockstack/client.ini
    Wallet is encrypted using your password and stored  at "/root/.blockstack/wallet.json", please make sure you create a backup.
        "status": true
    Re-exec as `"/usr/bin/python", "/usr/local/bin/blockstack", "api", "start", "--secrets", "3"`
    [2017-11-08 02:09:51,206] [DEBUG] [spv:103] (9.140481081538304) Using mainnet
    [2017-11-08 02:09:51,307] [DEBUG] [cli:419] (9.140481081538304) Load secrets from 3
    [2017-11-08 02:09:51,353] [DEBUG] [client:95] (9.140481081538304) Connect to
    [2017-11-08 02:09:51,357] [WARNING] [storage:632] (9.140481081538304) Storage implementation is missing a "get_immutable_handler" method
    [2017-11-08 02:09:51,359] [WARNING] [storage:632] (9.140481081538304) Storage implementation is missing a "put_immutable_handler" method
    [2017-11-08 02:09:51,361] [WARNING] [storage:632] (9.140481081538304) Storage implementation is missing a "delete_immutable_handler" method
    [2017-11-08 02:09:51,363] [WARNING] [storage:632] (9.140481081538304) Storage implementation is missing a "delete_mutable_handler" method
    [2017-11-08 02:09:51,505] [WARNING] [dropbox:188] (9) Config file '/root/.blockstack/client.ini': section 'dropbox' is missing 'token'.  Write access will be disabled
    [2017-11-08 02:09:51,506] [DEBUG] [client:110] (9.140481081538304) Loaded storage drivers ['disk', 'gaia_hub', 'dropbox', 's3', 'blockstack_resolver', 'http', 'dht']
        "status": true
    ATTENTION: default value of option force_s3tc_enable overridden by environment.

4. Frequently Asked Questions

Are there any other dependencies?

You should have curl installed. It’s used by the Linux script.

What is the Blockstack Core password? Is that the same as my 12-word password?

No. The password you enter at the command prompt is used to encrypt the ~/.blockstack/wallet.json file. You should NOT use your 12-word passphrase that you enter into the browser.

Why is there a separate Blockstack Core password?

The Blockstack API daemon uses it to process name registrations. The file ~/.blockstack/wallet.json is the wallet it uses to do so. This wallet is NOT the same as the one in the browser.

What if I forget the Blockstack Core password?

It’s usually not the end of the world, and you can usually recover. However, if you were in the process of registering a Blockstack ID, then that Blockstack ID will be lost.

If you forget your Blockstack Core password, you can recover by moving the ~/.blockstack directory out of the way. A new ~/.blockstack directory will be generated for you, and you can enter a new Blockstack Core password.

Why doesn’t the start work the second time?

If you close the web browser, the background daemon will keep running. It’s possible the daemon is still running. To stop it, you should run:

    $ bash ./ stop

If it still does not start, then it’s possible the API daemon left some old state around. In that case, try this as well:

    $ rm -rf /tmp/.blockstack_tmp

Why do I have to be root to run the browser?

You do not need to be root per se, but you do need to be in the docker group. Specifically, the UNIX socket at /var/run/docker.sock must be readable and writable to you. We do not recommend running as root. Instead, add yourself to the docker group with this command:

    $ sudo usermod -a -G docker $(whoami)

You may need to logout and log back in for the change to take effect. Alternatively, you can run su $(whoami), and the resulting shell will have the latest groups.

What if I have the blockstack CLI installed already?

If you have installed the CLI already, then you MUST back up your existing ~/.blockstack directory before running the browser. Once you stop the browser containers (with bash ./ stop), you can restore your ~/.blockstack directory to use the CLI again.

Help! Nothing is working!

If you’re still having trouble, there’s also a Web-only version available at You should only use this option of you cannot get Blockstack installed. If you go this route, you should uninstall Blockstack first. @odinho has written an excellent walk-through here.

Utter utter utter garbage
Cannot sign-in on Ubuntu 17.10
Cannot sign-in on Ubuntu 17.10

zsh: parse error near ')"


Hmm, can you try again with the whole URL in quotes? Like this:

$ curl -fsSL "$(. /etc/os-release; echo “$ID”)/gpg" | sudo apt-key add -

If that doesn’t work, could you try using bash instead of zsh?

Blockstack-Core password

also getting

 sudo apt-get install docker-ce
Reading package lists... Done
Building dependency tree       
Reading state information... Done
Package docker-ce is not available, but is referred to by another package.
This may mean that the package is missing, has been obsoleted, or
is only available from another source

E: Package 'docker-ce' has no installation candidate

curl -fsSL "$(. /etc/os-release; echo “$ID”)/gpg" | sudo apt-key add - 
curl: (22) The requested URL returned error: 404 Not Found
gpg: no valid OpenPGP data found.


Interesting. What’s the contents of your /etc/os-release? Also, which distro? The docker installation instructions are lifted directly from the Debian instructions on Docker CE’s website (

cat os-release 
VERSION="17.10 (Artful Aardvark)"
PRETTY_NAME="Ubuntu 17.10"

Thanks! You should be able to do sudo apt-get install Ubuntu ships with it. You may need to enable universe and multiverse in your sources.list file, if you haven’t already.


can you provide me with a working etc/apt/sources.list ?


Here’s the one I used:


after rm'ing .blockstack and .blockstack_tmp , I was able to pull the docker images and start.

However, I’m getting the same authentication behavior where a new window is opened instead of redirecting the localhost:8888 page.


Okay, thanks for bearing with me. This might be more related to the way xdg-open is behaving on your system. What happens if you run xdg-open from your shell.


@jude: These are excellent instructions! Especially with the FAQ.

I think they would be clearer if you actually removed the Debian specific parts though, and rather linked to those instructions along with the Docker-website. Maybe just note that your user should be part of the docker group.

That way there’s no branches, which can be hard to see/understand in prose. The FAQ section is also very helpful based on the questions we’ve seen so far :slight_smile:


opens a new tab with the correct URL. I tested with another site as well.

EDIT: blockstack opens with the URL http://localhost:8888/#coreAPIPassword=off when I do start if that helps.


If you run a Debian-based distro that does not have Docker…

If your distro does not ship Docker (Debian doesn’t, for example), then you’ll have to add the appropriate repository. These instructions may be slightly different for your distro. The instructions below are for Debian. You can find more distro-specific install instructions here.

Add the Docker Repository

This installs some helpful repository-managing tools:

   $ sudo apt-get install \
     apt-transport-https \
     ca-certificates \
     curl \
     gnupg2 \

We’ll add Docker’s GPG key:

    $ curl -fsSL "$(. /etc/os-release; echo "$ID")/gpg" | sudo apt-key add -

Next, we’ll add Docker’s repository:

    $ sudo add-apt-repository \
    "deb [arch=amd64]$(. /etc/os-release; echo "$ID") \
    $(lsb_release -cs) \

Now we can install Docker (community edition):

    $ sudo apt-get update && sudo apt-get install docker-ce

To check that Docker is running, you can use ps as follows:

    $ ps aux | grep docker
    root      1990  1.6  2.2 779588 46836 ?        Ssl  19:30   1:17 /usr/bin/dockerd -H fd://
    root      2003  0.0  0.5 636304 11224 ?        Ssl  19:30   0:02 docker-containerd -l unix:///var/run/docker/li
    bcontainerd/docker-containerd.sock --metrics-interval=0 --start-timeout 2m --state-dir /var/run/docker/libconta
    inerd/containerd --shim docker-containerd-shim --runtime docker-runc

Add yourself to the docker group

    $ sudo usermod -a -G docker $(whoami)

You will have to either log out and log back in, your start a new session under your username for this to take effect.

You can use the groups command to confirm that you’re in the docker group:

    $ groups | grep "docker"
    ... docker ...

Getting Further Help

Further distro-specific instructions can be found here.

I installed the Blockstack browser on Windows. But I can't sign in with my Blockstack ID
Testing browser blockstack

After successfully running the script pull command I call the start command. After creating a wallet I get the following error:

Status: Downloaded newer image for
83d43143c1ae9f346d2f01a712c866bf03102b5d21f61570bd45316574a5866a line 147: sensible-browser: command not found

I am on Arch.

P.S. This tutorial doesn’t mention that the Docker daemon should be started.


Hey @faurehu,

Thanks for the pointer! I’ll update to clarify that docker must be running.

Regarding sensible-browser, you’ll need to have xdg-utils installed. Specifically, you’ll need xdg-open to work. You can test with xdg-open to verify that xdg-open loads your preferred web browser and sends it to the given URL.

Testing browser blockstack

xdg-open is available to me but it won’t open

It errors with:

xdg-open: file '' does not exist

Try xdg-open

I wonder where the sensible-browser comes from, that’s a fallback in case xdg-open is not available? I also run Arch Linux and I have no sensible-browser, I think it is a Debianism. :slight_smile:


That worked so sensible-browser must be part of another package. Was your install conventional?