Install or uninstall the local browser

If all you want to do is create, manage, and fund an identity and then interact with DApps, you should use the web edition. If you have concerns about net censorship, heightened security concerns, or want to develop a DApp yourself, you may want to download and install the browser’s client edition; though it is not required. This page explains how to install or uninstall the browser client on a workstation.

About the client install

Remember, for most users the Blockstack Browser web application should suffice. You only need to install the client if you have additional, advanced concerns about Internet or identity. Though not required, some DApp developrs may find it useful to install the client edition.

The Blockstack Browser installer is a multiple-context installer. If you run it as a user, the installation is avalable only for that user. If you install as administrator, the installation installs for all users. To find an installer for your operating system, visit the browser installation page.

On Mac

Installation requires that you have macOS High Sierra 10.12 or higher. Do the following to install:

  1. Download the OSX installer from the browser installation page.
  2. Double-click the downloaded DMG file to launch the installer.

  3. Drag the to the Applications folder.
  4. Double-click the to launch it.

    The system displays a notice about opening the file:

  5. Choose Open.

    The system opens your default browser with the Blockstack Browser application, running from your machine (localhost). You’ll also see the Blockstack icon in your machine’s

    If you have loaded an identity already via the Blockstack web application, you are already logged into the local application:

On Windows

Installation requires that you have Windows 10 or higher. Do the following to install:

  1. Download the Windows installer from from the browser installation page.
  2. Double-click the installer package to launch it.

  3. Open the Wiindows Start menu and click on the recently added Blockstack Browser.

    The system displays a Windows Security Alert.

  4. Choose to Allow access.

    The system opens in the Blockstack Browser application.

On Linux

The Blockstack installation on Linux requires Docker. Before installing Blockstack, install the version of Docker appropriate for your operating system.

Note: The Blockstack script used in this procedure runs docker commands. Depending on how you installed and configure Dockered on your system, it may or may not be necessary to have root or sudo privileges. For this reason, the commands below show the use of sudo when interacting with the script or the docker executable. If your installation allows running Docker with lower privileges, you can omit it.

  1. Download the Linux installer from from the browser installation page.

    This downloads a script to your local drive.

  2. Open a terminal and navigate to the directory containing the downloaded script.

    When the script downloads, it is not executable.

  3. Set the executable bit on the file.

     $ chmod u+x
  4. Enter the command without any arguments to see the available subcommands.

     $ sudo ./
     blockstack docker launcher commands:
     Install-protocol-handler -> install a protocol handler for blockstack:// links
  5. Use the script to pull the Blockstack Docker images you need.

     $ sudo ./ pull

    Depending on your network speed, this can take some time.

  6. Use the docker image ls command to confirm you have the image.

     $ sudo docker image Is
     REPOSITORY	TAG	IMAGE ID	CREATED	v0.30.0	ad05fd844f59	2 days ago
  7. Install the protocol handler

     $  sudo ./ install-protocol-handler

     Registering protocol handler
  8. Start the Blockstack containers.

     $ sudo ./ start


     Registering protocol handler

    The system launches the Blockstack Browser application for you.

Until you stop the Blockstack containers, the application will continue to run on your system. To display the status of the Blockstack containers, you can use the docker container ls command.

$ sudo docker container ls --format '{{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}\t{{.Names}}'

Use ./ stop to stop the Blockstack Browser and its containers.

Uninstall the browser

If you installed the browser using an installer, follow the instructions for your operating system.

On Mac

  1. Quit the Blockstack application if it is running.

  2. Check if you have a Blockstack device and eject it if you do.

  3. Use the Finder to open the Applications folder.
  4. Locate the Blockstack application.
  5. Open your Applications folder and locate the
  6. Drag the appliation to the trash.
  7. Delete the /Users/USERNAME/Library/Application Support/Blockstack folder.

    From the command line:

    $ rm -r /Users/meepers/Library/Application\ Support/Blockstack

On Windows

  1. Open the Start menu.
  2. Click Settings > System.
  3. Open for the Apps & features item.

  4. Locate the Blockstack Browser and choose Uninstall.

On Linux

Your Blockstack instalaltion relies on Docker containers and their associated images. It also includes a supporting protocol handler you must remove. If you installed Docker so that you can run Blockstack, you can uninstall Docker as well, but that is not explained here.

Do the following to uninstall Blockstack:

  1. Stop and remove the Docker containers if they are running.

     $ sudo ./ stop
     stopping the running blockstack-browser containers
  2. Remove the associated Blockstack images.

     $ sudo docker image ls
     REPOSITORY	                          TAG	    IMAGE ID	    CREATED	v0.30.0	ad05fd844f59	3 days ago
     $ sudo docker image rm ad05fd844f59

     Untagged : browser :vO.30.0
     Deleted: Sha256:ad05fd844f5948blee06a0a09228df946478393c0a7588cbc65dlb8817f5b34e
     Deleted: Sha256:7c3d0043f2ba01cf285f3fe09701b086c349b6380c2e42f25b31ac65c6626ec8
     Deleted: sha256:54ea2aa7d7d000e7483f299eeca9e5466fa86231f4cd4cld3c3096d97e61c5df
     Deleted: sha256:38e61054355adefc3c2de031462114a9946cfc0e44444a38a27d0f115aba0da2
  3. Use the script to remove the protocol handler

     $ sudo ./ remove-protocol-handler
  4. Delete the script.

     $ rm