Skip to main content

Advanced Installation

info

This page will go into the details of the various different ways to install Chia. If you already installed Chia as part of the Farming Guide, then feel free to skip ahead to the Plotting Basics page.

There are various ways to install Chia, with the best method depending on what you intend to do:

  • If you simply wish to use the Chia wallet, or to run a farm on a single personal computer, then we recommend installing the GUI from our official downloads page for Windows and MacOS, and for Linux users to install the package as described below. The GUI is the simplest way to interact with the Chia client and ideal for most non-developer use cases.

  • If you intend to run a dedicated Chia full node on a server and connect to it programmatically using the RPC interface, the best method would be to install and run Chia via the command line on a proper server environment.

  • If you intend to do Chialisp development or build projects that leverage Chia, you have the options of either using an installer (the recommended pattern), or installing from source.

  • Lastly, if you plan on making contributions to the source code, then installing Chia from source would be your path.

In summary, unless you already knew before reading this page that you should be installing from source, chances are your best path will be to install from our official downloads page or a Linux package, depending on your OS.

System Requirements​

The minimum supported specs are that of the Raspberry Pi 4, 4GB model:

  • Quad core 1.5Ghz CPU (must be 64 bit)
  • 4 GB RAM
  • As of Chia version 2.5, Python versions 3.9 and later are supported

Drive Format​

Chia plot files are at least 108GB in size (for K32). To plot successfully requires drives formatted to support large files. Formats that will work include NTFS, APFS, exFAT, and ext4. Do not use drives with FAT formatting (for example FAT12, FAT16, and FAT32), or else plotting will fail. Future versions of Chia will check for unsupported drives, but for now it's up to each user to check their drive format.

Sleep kills plots​

If the computer or hard drives go to sleep during the plotting process, it will fail, and you will need to start over. Please ensure all sleep, hibernate and power saving modes for your computer and hard drives are disabled before starting the Chia plotting process. In the future, Chia will have a resume plot feature. In the meantime, if you do get a failed plot, delete all *.tmp files before starting a new plot.

Install​

Using the CLI​

This method is intended for linux environments

# Install packages
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg

# Add GPG key
curl -sL https://repo.chia.net/FD39E6D3.pubkey.asc | sudo gpg --dearmor -o /usr/share/keyrings/chia.gpg

# Set up repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/chia.gpg] https://repo.chia.net/debian/ stable main" | sudo tee /etc/apt/sources.list.d/chia.list > /dev/null
sudo apt-get update

# Install chia-blockchain
sudo apt-get install chia-blockchain

# Use chia-blockchain-cli instead for CLI only

From Source​

This method is primarily intended for contributing to the Chia codebase

# Download chia-blockchain
git clone https://github.com/Chia-Network/chia-blockchain -b latest --recurse-submodules

# Change directory
cd chia-blockchain

# Install dependencies
sh install.sh

# Activate virtual environment
. ./activate

# Initialize
chia init

The following is how you update to the latest version:

# Change directory
cd chia-blockchain

# Activate the virtual environment
. ./activate

# Stop running services
chia stop -d all

# Deactivate the virtual environment
deactivate

# Remove the current virtual environments
rm -r venv
rm -r .penv
rm -r .venv

# Pull the latest version
git fetch
git checkout latest
git reset --hard FETCH_HEAD --recurse-submodules

# If you get RELEASE.dev0 then delete the package-lock.json in chia-blockchain-gui and install.sh again

# This should say "nothing to commit, working tree clean"
# if you have uncommitted changes, RELEASE.dev0 will be reported
git status

# Install the new version
sh install.sh

# Activate the virtual environment
. ./activate

# Initialize the new version
chia init

Raspberry Pi 4​

note

Chia does not support the Raspberry Pi 3, and we do not recommend running the GUI on the 4GB Raspberry Pi 4 model.

It is highly recommended you put the Chia blockchain and wallet database on an SSD or NVMe drive, rather than the SD card.

Swap​

It is suggested that you set up 1024 MiB of swap:

Run the following commands to set up the swap:

sudo dd if=/dev/zero of=/swap bs=1M count=1024
sudo chmod 600 /swap
sudo mkswap /swap
sudo swapon /swap

Add this line to /etc/fstab so that swap available on reboot:

/swap swap swap defaults 0 0

Setup​

Run the following commands to prepare for installation:

# Requirements to compile the blockchain
sudo apt-get install -y build-essential python3-dev

# If you are not using Raspbian 64, add this
export PIP_EXTRA_INDEX_URL=https://www.piwheels.org/simple/

# Make sure you have 64-bit Python 3.9 or later
python3 -c 'import platform; print(platform.architecture())'

Proceed​

note

If you run into an error during the build process, make sure you are running a 64-bit version of the OS.

You can check by running uname -a. If it says arm7l, you need a 64-bit version of the OS. The uname -a output should end with aarch64 GNU/Linux.

Finally, follow the typical from source installation for Linux to continue.

Disable Timelord​

This is not necessary when installing from source.

However, if you install Chia in some other way, disable the timelord build process:

export BUILD_VDF_CLIENT=N

Other environments​

Installation instructions for docker are found on the container repo: Docker

Directory Structure​

.chia/
└── mainnet/
      ├─ config/
      │      ├─ config.yaml
      │      └─ ssl/
      ├─ db/
      ├─ log/
      │      └─ debug.log
      ├─ run/
      └─ wallet/

All data used by the Chia blockchain is stored at the location set with the CHIA_ROOT environment variable, which defaults to ~/.chia/mainnet (the hidden folder .chia inside of your home directory) if unset.

The blockchain database is stored under the db subdirectory. It is possible to copy the database file to use as a backup or put on another machine. To resync the full node from the start, delete the database file and restart the node.

The config file under the config subdirectory. Its name is config.yaml, and it can be used to find the root cause of problems.

It is possible to configure the CHIA_ROOT environment variable to another location. A common use for this would be to switch it to ~/.chia/testnet to have a separate config for the testnet.

CLI​

Using the CLI gives greater and more precise control over the various Chia services such as the full node. As of 1.8.2, when installing from an installer or package CLI commands will be automatically added to your path for Windows and Linux. For more details on the commands, read the CLI Reference.

The CLI commands are stored in the following location:

/Applications/Chia.app/Contents/Resources/app.asar.unpacked/daemon

To be able to use these commands without going to that directory in the terminal, add it to the path.

This can be done by running the following command:

export PATH=/Applications/Chia.app/Contents/Resources/app.asar.unpacked/daemon:$PATH

To load this on startup, add it to the .bashrc, .bash_profile, or .zshrc file depending on which is used by the shell.

GUI​

The GUI is the most user-friendly method of interacting with Chia for non-developer uses, and it can be installed manually from the CLI if you installed from source.

# Install the GUI
. ./install-gui.sh

# Start the GUI
sh start-gui.sh

The following is how you update to the latest version:

# Change directory into the GUI
cd chia-blockchain-gui

# Pull the latest version
git fetch

# Change directory
cd ..

# Change permissions on install script
chmod +x ./install-gui.sh

# Install the new version of the GUI
./install-gui.sh

# Start the GUI
bash start-gui.sh

Initial Startup​

Upon launch the GUI will set everything up automatically, however if installing from source then the initial setup needs to be done manually via the CLI.

First, initialize the Chia configuration files:

chia init

Then, generate your keys:

chia keys generate

Finally, start the farmer and its full node:

chia start farmer

Systemd​

Linux users who have installed the chia-blockchain-cli package using apt, yum, or dnf will receive systemd configuration files for initializing and managing the Chia processes. Each Chia service needs to be managed separately with systemd, except for the chia-daemon, which will be initialized automatically when any other Chia service is started with systemd (for example, the data-layer service will not automatically start the wallet service - both need to be started individually with systemd). A user must be specified during the initialization to ensure the resulting process can find the Chia root directory. The included systemd files support the default Chia directory location of /home/<user>/.chia/mainnet only.

To start a Chia process with systemd, the command format is systemctl start chia-<service-name>@<user>. For example, if starting a Chia full node for the Linux user ubuntu, the command would be:

systemctl start chia-full-node@ubuntu

To start the full-node at system boot:

systemctl enable chia-full-node@ubuntu

The services available to be managed with systemd are:

chia-crawler
chia-data-layer
chia-data-layer-http
chia-farmer
chia-full-node
chia-harvester
chia-introducer
chia-seeder
chia-timelord
chia-wallet

Note that the chia-timelord service runs the timelord coordinator service, but not the VDF clients.

Troubleshooting​

Sometimes stray daemons left over from previously running processes will cause strange bugs/errors when upgrading to a new version. Make sure all daemons and chia processes are killed before installing or upgrading.

This is normally done by executing chia stop -d all from the upgrade example above.
But it doesn't hurt to double check using ps -Af | grep chia to make sure there are no chia processes left running. You may have to manually kill the chia daemon if an install and chia start was performed without first running chia stop -d all

If all else fails, rebooting the machine and restarting the chia daemon/processes usually does the trick.

Testnets​

To join a testnet, follow the instructions on How to Join the Official Testnet.

It is recommended that you keep a separate testnet environment by prepending CHIA_ROOT="~/.chia/testnetx" to all of your cli commands. For example, CHIA_ROOT="~/.chia/testnet11" chia init. An easier way to do this is to run export CHIA_ROOT="~/.chia/testnet11" so that all commands will use testnet11 instead of mainnet. You can update all config values to the testnet values by running chia configure -t true.

Beta and release candidate installations​

From Source​

This method is primarily intended for contributing to the Chia codebase

# Download chia-blockchain
git clone https://github.com/Chia-Network/chia-blockchain -b latest --recurse-submodules

# Change directory
cd chia-blockchain

# Checkout the beta or release candidate by tag, tags can be found https://github.com/Chia-Network/chia-blockchain/tags.
git checkout tags/2.1.2-rc2

# Install dependencies
sh install.sh

# Activate virtual environment
. ./activate

# Initialize
chia init

From packaged installer​

# Install packages
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg

# Add GPG key
curl -sL https://repo.chia.net/FD39E6D3.pubkey.asc | sudo gpg --dearmor -o /usr/share/keyrings/chia.gpg

# Set up repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/chia.gpg] https://repo.chia.net/prerelease/debian/ prerelease main" | sudo tee /etc/apt/sources.list.d/chia-blockchain-prerelease.list > /dev/null
sudo apt-get update

# Install chia-blockchain
sudo apt-get install chia-blockchain

# Use chia-blockchain-cli instead for CLI only