# Getting started
This is a step-by-step guide for installing and running a Filecoin node connected to the testnet on your local machine. Subsequent tutorials explain how to mine Filecoin.
# Table of contents
- Getting started
# Minimal requirements
To run a Lotus node, your computer must have:
- macOS or Linux installed. Windows is not yet supported.
- 8-core CPU and 32 GiB RAM. Models with support for Intel SHA Extensions (AMD since Zen microarchitecture, or Intel since Ice Lake) will significantly speed things up.
- Enough space to store the current Lotus chain (preferably on an SSD storage medium). The chain grows at approximately 12 GiB per week. The chain can be also synced from trusted state snapshots and compacted.
# Installing Go
The build process for
venus requires Go (opens new window) >= v1.16.
Installing Go for the first time? We recommend this tutorial (opens new window) which includes environment setup.
Due to the use of
venus, a C compiler is required to build it whether a prebuilt library is being used or it is compiled from source. To use
export CC=gcc), v7.4.0 or higher is required.
The build process will download a static library containing the Filecoin proofs implementation (opens new window) (which is written in Rust).
NOTICE: To build proofs from source, (1) a Rust development environment must be installed and (2) the environment variable
FFI_BUILD_FROM_SOURCE=1must be set. More information can be found in filecoin-ffi (opens new window).
# Installing Rustup
Lotus needs rustup (opens new window). 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
rustc are found in their rustup-configured locations.
# Install system dependencies
sudo pacman -Syu opencl-icd-loader gcc git bzr jq pkg-config opencl-icd-loader opencl-headers hwloc
sudo apt install mesa-opencl-icd ocl-icd-opencl-dev gcc git bzr jq pkg-config curl clang build-essential hwloc libhwloc-dev wget -y && sudo apt upgrade -y
sudo dnf -y install gcc make git bzr jq pkgconfig mesa-libOpenCL mesa-libOpenCL-devel opencl-headers ocl-icd ocl-icd-devel clang llvm wget hwloc libhwloc-dev
sudo zypper in gcc git jq make libOpenCL1 opencl-headers ocl-icd-devel clang llvm hwloc && sudo ln -s /usr/lib64/libOpenCL.so.1 /usr/lib64/libOpenCL.so
Amazon Linux 2:
sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm; sudo yum install -y git gcc bzr jq pkgconfig clang llvm mesa-libGL-devel opencl-headers ocl-icd ocl-icd-devel hwloc-devel
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.
Check if you already have the XCode Command Line Tools installed via the CLI, run:
If this command returns a path, you can move on to the next step. Otherwise, to install via the CLI, run:
To update, run:
sudo rm -rf /Library/Developer/CommandLineTools xcode-select --install
# Install Homebrew
We recommend that MacOS users use Homebrew (opens new window) to install each of the necessary packages.
Use the command
brew installto install the following packages:
brew install go bzr jq pkg-config rustup hwloc
# Installing dependencies
venusgit repository and enter it:
mkdir -p /path/to/filecoin-project git clone https://github.com/filecoin-project/venus.git /path/to/filecoin-project/venus
Load all the Git submodules:
git submodule update --init --recursive
Initialize the build dependencies:
NOTICE: The first
depsstart up can be slow, as very large parameter files are either downloaded or generated locally in
/var/tmp/filecoin-proof-parameters. Have patience; future runs will be faster.
# Building Filecoin and running tests
Build the binary:
Run the unit tests:
go run ./build test
Optionally, building and tests can be combined:
go run ./build best
Other handy build commands include:
# Check the code for style and correctness issues go run ./build lint # Run different categories of tests by toggling their flags go run ./build test -unit=false -integration=true -functional=true # Test with a coverage report go run ./build test -cover # Test with Go's race-condition instrumentation and warnings (see https://blog.golang.org/race-detector) go run ./build test -race # Deps, Lint, Build, Test (any args will be passed to `test`) go run ./build all
NOTICE: Any flag passed to
go run ./build test(e.g.
-cover) will be passed on to
For all problems with the build, please consult the Troubleshooting (opens new window) section of this documentation.
# Start running Filecoin
venushas been run on the system before, remove existing Filecoin repo (this will delete all previous filecoin data):
rm -rf ~/.venus
Start the venus daemon:
This should return "My peer ID is
<peerID> is a long CID (opens new window) string starting with "Qm".
Print a list of bootstrap node addresses:
venus config bootstrap.addresses
Choose any address from the list you just printed, and connect to it (Automatic peer discovery and connection coming soon.):
venus swarm connect <any-filecoin-node-mulitaddr>
NOTICE: This can be slow the first time. The filecoin node needs a large parameter file for proofs, stored in
/tmp/filecoin-proof-parameters. It is usually generated by the
depsbuild step. If these files are missing they will be regenerated, which can take up to an hour. We are working on a better solution.
- Check the node's connectivity:
venus swarm peers # list addresses of peers to which you're connected
The node should now be connected to some peers and will begin downloading and validating the blockchain.
NOTICE: The daemon is now running indefinitely in its own Terminal (
Ctrl + Cto quit). To run other
venuscommands, open a second Terminal tab or window (
Cmd + Ton Mac)._
# Wait for chain sync
🎉 Congratulations, you're now connected to Filecoin! The daemon is now busy syncing and validating the existing blockchain, which can take awhile -- hours or even days depending on network age and activity.
During this initial sync time ther will be intense activity on one CPU core. Find out what the current block height is first by visiting the network stats page (opens new window) then observe the nodes syncing progress:
venus sync status
# Viewing network information
There are a few visualisation tools to help users understand what is happening within the Filecoin network, such as the official network stats (opens new window) page as well as the community-managed block explorers filscan.io (opens new window), filscout.io (opens new window), and filfox.io (opens new window).