Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

BitGrin - Build, Configuration, and Running

Read this in other languages: Español, Korean, 日本語.

Supported Platforms

Longer term, most platforms will likely be supported to some extent. BitGrin's programming language rust has build targets for most platforms.

What's working so far?

  • Linux x86_64 and MacOS [bitgrin + mining + development]
  • Windows 10 coming soon with GUI


  • rust 1.34+ (use rustup- i.e. curl -sSf | sh; source $HOME/.cargo/env)
    • if rust is already installed, you can simply update version with rustup update
  • clang
  • ncurses and libs (ncurses, ncursesw5)
  • zlib libs (zlib1g-dev or zlib-devel)
  • pkg-config
  • libssl-dev
  • linux-headers (reported needed on Alpine linux)
  • llvm

For Debian-based distributions (Debian, Ubuntu, Mint, etc), all in one line (except Rust):

apt install build-essential cmake git libgit2-dev clang libncurses5-dev libncursesw5-dev zlib1g-dev pkg-config libssl-dev llvm

For Mac:

xcode-select --install
brew install --with-toolchain llvm
brew install pkg-config
brew install openssl

Build steps

git clone
cd bitgrin
cargo build --release

BitGrin can also be built in debug mode (without the --release flag, but using the --debug or the --verbose flag) but this will render fast sync prohibitively slow due to the large overhead of cryptographic operations.

Build errors

See Troubleshooting

What was built?

A successful build gets you:

  • target/release/bitgrin - the main bitgrin binary

All data, configuration and log files created and used by bitgrin are located in the hidden ~/.bitgrin directory (under your user home directory) by default. You can modify all configuration values by editing the file ~/.bitgrin/main/bitgrin-server.toml.

It is also possible to have bitgrin create its data files in the current directory. To do this, run

bitgrin server config

Which will generate a bitgrin-server.toml file in the current directory, pre-configured to use the current directory for all of its data. Running bitgrin from a directory that contains a bitgrin-server.toml file will use the values in that file instead of the default ~/.bitgrin/main/bitgrin-server.toml.

While testing, put the bitgrin binary on your path like this:

export PATH=/path/to/bitgrin/dir/target/release:$PATH

Where /path/to/bitgrin/dir is your absolute path to the root directory of your BitGrin installation.

You can then run bitgrin directly (try bitgrin help for more options).


BitGrin attempts to run with sensible defaults, and can be further configured via the bitgrin-server.toml file. This file is generated by bitgrin on its first run, and contains documentation on each available option.

While it's recommended that you perform all bitgrin server configuration via bitgrin-server.toml, it's also possible to supply command line switches to bitgrin that override any settings in the file.

For help on bitgrin commands and their switches, try:

bitgrin help
bitgrin wallet help
bitgrin client help


docker build -t bitgrin -f etc/Dockerfile .

For floonet, use etc/Dockerfile.floonet instead

You can bind-mount your bitgrin cache to run inside the container.

docker run -it -d -v $HOME/.bitgrin:/root/.bitgrin bitgrin

If you prefer to use a docker named volume, you can pass -v dotbitgrin:/root/.bitgrin instead. Using a named volume copies default configurations upon volume creation

Cross-platform builds

Rust (cargo) can build bitgrin for many platforms, so in theory running bitgrin as a validating node on your low powered device might be possible. To cross-compile bitgrin on a x86 Linux platform and produce ARM binaries, say, for a Raspberry Pi.

Using bitgrin

The wiki page How to use bitgrin and linked pages have more information on what features we have, troubleshooting, etc.

Mining in BitGrin

Please note that all mining functions for BitGrin have moved into a separate, standalone package called bitgrin-miner. Once your BitGrin code node is up and running, you can start mining by building and running bitgrin-miner against your running BitGrin node.

For bitgrin-miner to be able to communicate with your bitgrin node, make sure that you have enable_stratum_server = true in your bitgrin-server.toml configuration file and you have a wallet listener running (bitgrin wallet listen).