# Lotus: install and setup

This guide covers how to install the Lotus applications and launch a Lotus Node.. This guide covers installing lotus, lotus-miner and lotus-worker to your computer, and then runs through setting up a Lotus node. For information on running the miner, check the Lotus Miner documentation.

# Minimal requirements

To run a Lotus node, your computer must have:

  • macOS or Linux installed. Windows is not yet supported.
  • a quad-core CPU. Models with support for Intel SHA Extensions (AMD since Zen microarchitecture, or Intel since Ice Lake) will significantly speed things up.
  • 8 GiB RAM
  • Enough space to store the current Lotus chain (preferably on an SSD storage medium). The chain grows at approximately 12 GiB per week.


These are the minimal requirements to run a Lotus node. Hardware requirements for Miners are different.

# Linux

The following instructions are specific to Linux installations. Head to the macOS section if you want to install Lotus on a Mac.

# Software dependencies

You will need the following software installed to install and run Lotus.

# System-specific

Building Lotus requires some system dependencies, usually provided by your distribution.

Linux distribution Dependency install command
Arch Linux sudo pacman -Syu opencl-icd-loader gcc git bzr jq pkg-config opencl-icd-loader opencl-headers
Ubuntu/Debian sudo apt update && sudo apt install mesa-opencl-icd ocl-icd-opencl-dev gcc git bzr jq pkg-config curl -y && sudo apt upgrade -y
Fedora sudo dnf -y update && sudo dnf -y install gcc git bzr jq pkgconfig mesa-libOpenCL mesa-libOpenCL-devel opencl-headers ocl-icd ocl-icd-devel clang llvm
OpenSUSE sudo zypper in gcc git jq make libOpenCL1 opencl-headers ocl-icd-devel clang llvm && sudo ln -s /usr/lib64/libOpenCL.so.1 /usr/lib64/libOpenCL.so

# Rustup

Lotus needs rustup. The easiest way to install it is:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh


Make sure your $PATH variable is correctly configured after the rustup installation so that cargo and rustc are found in their rustup-configured locations.

# Go

To build Lotus, you need a working installation of Go 1.14 or higher:

wget -c https://dl.google.com/go/go1.14.7.linux-amd64.tar.gz -O - | sudo tar -xz -C /usr/local

Make sure that /usr/local/go/bin is in your PATH. If you are running into problems, check the official Go installation instructions for your operating system.

# Build and install Lotus

Once all the dependencies are installed, you can build and install the Lotus suite (lotus, lotus-miner, and lotus-worker).

  1. Clone the repository:

    git clone https://github.com/filecoin-project/lotus.git
    cd lotus/
  2. Checkout the branch corresponding to the network you want to join. You can look up the correct branch or tag for the network you want to join in the networks dashboard:

    git checkout <branch_or_tag>

    Currently, the master branch corresponds to testnet.

  3. If you are in China, check out the specific tips.

  4. If you have an AMD Zen or Intel Ice Lake CPU (or later), enable the use of SHA extensions by adding these two environment variables:

    export RUSTFLAGS="-C target-cpu=native -g"

    See the Native Filecoin FFI section for more details about this process.

  5. Build Lotus:

    make clean all
    sudo make install

    This will put lotus, lotus-miner and lotus-worker in /usr/local/bin.

    lotus will use the $HOME/.lotus folder by default for storage (configuration, chain data, wallets, etc). See advanced options for information on how to customize the Lotus folder.

  6. Lotus should now be installed on your computer.

# Native Filecoin FFI

Some newer CPU architectures like AMD's Zen and Intel's Ice Lake, have support for SHA extensions. Having these extensions enabled significantly speeds up your Lotus node. To make full use of your processor's capabilities, make sure you set the following variables before building from source:

export RUSTFLAGS="-C target-cpu=native -g"

This method of building does not produce portable binaries. Make sure you run the binary on the same computer as you built it.

# Systemd service files

Lotus provides Systemd service files. They can be installed with:

make install-daemon-service
make install-miner-service

Once installed, you should be able to control Lotus using systemctl [start|stop] lotus-daemon.


By default, the lotus-daemon service file redirects the logging output to /var/log/lotus/daemon.log, so journalctl displays nothing.

# macOS

These instructions are specific to macOS. If you are installing Lotus on a Linux distribution, head over to the Linux section.

# XCode Command Line Tools

Lotus requires that X-Code CLI tools be installed before building the Lotus binaries.

  1. Check if you already have the XCode Command Line Tools installed via the CLI, run:

    xcode-select -p

    If this command returns a path, you can move on to the next step. Otherwise, to install via the CLI, run:

    xcode-select --install
  2. To update, run:

    sudo rm -rf /Library/Developer/CommandLineTools
    xcode-select --install

# Install Homebrew

We recommend that MacOS users use Homebrew to install each of the necessary packages.

  1. Use the command brew install to install the following packages:

    brew install go bzr jq pkg-config rustup
  2. Clone the repository:

    git clone https://github.com/filecoin-project/lotus.git
    cd lotus/
  3. Checkout the branch corresponding to the network you want to join. You can look up the correct branch or tag for the network you want to join in the networks dashboard:

    git checkout <branch_or_tag>

    Currently, the master branch corresponds to testnet.

  4. If you are in China, check out the specific tips.

  5. Build Lotus:

    make clean && make all
    sudo make install
  6. You should now have Lotus installed.

# Start the Lotus daemon

The lotus application runs as a daemon and a client to control and interact with that daemon. A daemon is a long-running program that is usually run in the background.

To start the Lotus daemon run:

lotus daemon
## When running with systemd do:
# systemctl start lotus-daemon

During the first run, Lotus will:

  • Setup its data folder at ~/.lotus.
  • Download the necessary proof parameters. This is a few gigabytes of data that is downloaded once.
  • Start syncing the Lotus chain.

The daemon will start producing lots of log messages right away.


Do not be concerned by the number of warnings and sometimes errors showing in the logs. They are usually part of the usual functioning of the daemon as part of a distributed network.

# Chain sync

As in many other blockchains, the Lotus Node will need to sync to the tip of the chain after learning about this. We call this process chain sync. First, the headers for every block will be synced from tip to bottom. Afterward, blocks will be fetched and verified from bottom to top. To inspect the current sync status run:

lotus sync status

You can also interactively wait for the chain to be fully synced:

lotus sync wait


Syncing the Filecoin chain can be a very slow process, and the state size is quite large. Unless you need the full historical chain state, we suggest just pulling a recent snapshot and using that to skip syncing older sections of the chain.

For now, you can download the latest state snapshot here

Then start your lotus daemon with:

lotus daemon --import-snapshot <snapshot>.car

For more information about chain snapshots, see the Chain snapshots section.

To check how far behind you are when syncing the chain, run the following command:

date -d @$(./lotus chain getblock $(./lotus chain head) | jq .Timestamp)

# Interact with the daemon

The lotus command allows you to interact with a running Lotus daemon. The lotus-miner and lotus-worker commands work in the same way.

Lotus comes with built-in CLI documentation:

# Show general help
lotus --help
# Show specific help for the "client" subcommand
lotus client --help

For example, after your Lotus daemon has been running for a few minutes, use lotus to check the number of other peers that it is connected to in the Filecoin network:

lotus net peers