INSTALL

Make sure you are downloading Chia software from the chia.net domain. Do not use any other download source.

Official installer links can be found on chia.net/download and this wiki page.

---

To install the chia-blockchain, follow the instructions according to your operating system. After installing, follow the remaining instructions in the Quick Start Guide to run the software. You should read the release notes and the wiki/repository FAQ.

Jump to:	Windows	MacOS	Ubuntu	CentOS / Red Hat	WSL2	Amazon Linux 2	Other platforms

Install from source	Update from source

All keys and plots from version prior to Beta 8 (released July 16, 2020) are deprecated and can be deleted. Plots from both Beta 8 and newer should work on mainnet.

Minimum Specs

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
• Python 3.7, 3.8, and 3.9 (there are currently known issues with 3.10)

Drive format support

Chia plot files are at least 108GB in size (for K32). To plot successfully requires drives formatted to support large files; e.g. NTFS, APFS, exFAT, ext4, etc. Do not use drives with FAT formatting (FAT12, FAT16, or 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

The Chia plotting process takes multiple of hours to complete. If the computer or hard drives goes to sleep during the plotting process, the plotting fails 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 resume plot feature. In the meantime, if you do get a failed plot, delete all *.tmp files before starting a new plot.

Updating from Release Candidate to 1.0:

Keys and configs from RC3 and newer should automatically migrate. For more details, read the FAQ. No testnet/TXCH coins migrate to mainnet. Mainnet coins are forever, however.

Windows

Install the Windows installer - Chia Blockchain Windows

As the Chia code signing certificate is new you will likely have to ask to keep the download and when you run the installer, you will have to choose "More Info" and "Run Anyway" to be able to run the installer. There is no need to use the command line. Some Windows anti-virus applications are seeing the download as a false positive. You can see the entire source code and build method here so we think it's safe for you to ask those tools to ignore it. Running the installer while plotting on a previous version will stop your plotting process, so be careful.

You can now proceed to the Quick Start Guide

macOS

macOS Mojave (10.14.x) or newer is required.

Install the macOS .dmg installer - Chia Blockchain MacOS

When the installer first runs it will import or create multiple keys and add them to the macOS keychain. You may be prompted up to 3 times for your password. We suggest choosing "always allow."

You can now proceed to the Quick Start Guide

Install from source - macOS

To build a development version, make sure brew is available before starting the setup and that python 3.7 or newer is installed.
See install from source for detailed instruction.

Ubuntu/Debian

We have a GUI installer (x86_64) for Ubuntu 18.04 Desktop and newer and Debian Buster w GUI and newer. There is also a GUI installer for ARM64 Ubuntu and Debian/Raspberry Pi OS 64. Binary CLI tools can be found in /usr/lib/chia-blockchain/resources/app.asar.unpacked/daemon/

Install from source - Ubuntu

See install from source for detailed instruction.

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.

CentOS/Red Hat/Fedora

We have a GUI installer for RH/CentOS 8.0 and Fedora 28 and newer.

Install from source - CentOS/Red Hat/Fedora

See install from source for detailed instruction.

Install from binary wheels

python3.7 -m venv venv
ln -s venv/bin/activate
. ./activate
pip install --upgrade pip
pip install --extra-index-url https://pypi.chia.net/simple/ chia-blockchain==1.3.0 miniupnpc==2.1

WSL2

You can run chia-blockchain in Ubuntu 20.04 LTS via WSL2 on Windows.

NOTE: WSL2 plotting is currently only slightly faster than plotting on the native windows client. WSL2 requires significant tweaking to set up correctly. If you find that daunting, it's probably easier to just use the native windows client.

You can not run the GUI as WSL2 doesn't yet support graphical interfaces from WSL2.

Check if you already have WSL2 or WSL1 installed:

From PowerShell, type:

wsl -l -v

If you get a listing of help topics for wsl commands, you have WSL1, and need to upgrade. To upgrade, follow the instructions here. If you get a blank result or a listing of installed Linux versions, you have WSL2 and are OK to proceed.

If WSL is not installed:

From an Administrator PowerShell:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all

You will be prompted to reboot.

Installing a new WSL2 instance:

Install Ubuntu 20.04 LTS from the Microsoft Store and run it and complete its initial install steps. You now have a linux bash shell environment that can run linux native software on Windows.

Install from source - WSL2

See install from source for detailed instruction.

Running a standalone Windows wallet gui is deprecated but may return in later versions. You can run the Windows version and share keys. You can also plot in WSL2 and migrate the plots to a Windows farmed plot directory.

Increasing the WSL Maximum Storage Capacity

WSL2 uses a Virtual Hardware Disk (VHD) to store files, and it automatically resizes as files grow. However, the VHD has an initial maximum size of 256 GB. Therefore, the default WSL2 VHD is probably only capable of plotting k=30 plots. To plot anything larger, you will need to increase the maximum allowable size. Follow the guide here.

Setting a maximum limit to WSL2 memory access

If you try plotting Chia in WSL2 without limiting the memory access, WSL2 will use 100% of your available machine's memory, and your computer will get bogged down and begin swapping memory to your hard drive. This will severely cripple your plotting speeds. To set the maximum memory that WSL2 is allowed to use, create a configuration file as described in this guide.

WSL VHD Plotting Nuances

Plotting within WSL2 can write to either the native VHD (which is EXT4) or to any other drive, which can be NTFS or any other FS-type. Writing to the native VHD is faster than writing out to another drive.

Plotting uses three commands for directory control:

-t for initial temp directory. Phases 1 and 2 happen here.

-2 for secondary temp directory. Phase 3 (compression) happens here.

-d for final destination. Phase 4 happens here.

Plotting works such that -t and -2 require the exact same amount of storage space. Therefore, if -t and -2 point to the same drive, that drive needs 2x the final file size + 1x the max working file size.

For maximum speed, -t and -2 should be inside the WSL2 filesystem. Something like: -t ~/chia_temp -2 ~/chia_temp. Just beware that the WSL2 VHD will need a much larger maximum capacity.

-d can point to any other drive for the final destination.

Amazon Linux 2

Install from source - Amazon Linux 2

See install from source for detailed instruction.

Install from binary package

# Install chia-blockchain as a binary package
python3.7 -m venv venv
ln -s venv/bin/activate
. ./activate
pip install --upgrade pip

pip install --extra-index-url https://pypi.chia.net/simple/ chia-blockchain==1.3.0 miniupnpc==2.1

Other install methods and environments

• Raspberry Pi 4
• Docker
• FreeBSD Install
• Ubuntu Binary Install
• OpenBSD Install

You need Python 3.7 or newer.

Chia strives to provide binary wheels for modern systems. If your system does not have binary wheels, you may need to install development tools to build some Python extensions from source. If you're attempting to install from source, setting the environment variable BUILD_VDF_CLIENT to N will skip trying to build Timelord components that aren't very cross platform, e.g. export BUILD_VDF_CLIENT=N.

Create a virtual environment

Your installation goes inside a virtual environment.

There are lots of ways to create and manage a virtual environment. This is just one.

python3.7 -m venv venv
source venv/bin/activate
pip install --upgrade pip

Wheels can be in source or binary format. Binary wheels are specific to an operating system and python version number. Source wheels require development tools.

Chia hosts some binary wheels that are not available from PyPI. This step is optional, but it may succeed where building from source can take a while or fail in hard-to-debug ways. If wheels are not available for your system, this step will fail. But you can try it anyway.

pip install -i https://pypi.chia.net/simple/ miniupnpc==2.1 zstd

Install chia-blockchain.

pip install chia-blockchain==1.3.0

Before you use chia-blockchain in future, you must "enter" your virtual environment.

source venv/bin/activate
chia -h

Install from source

*This instruction is for MacOS, Ubuntu, CentOS, RedHat, WSL2, Amazon Linux 2 and possibly *NIX like OSes.

# Prerequisite: git 

git clone https://github.com/Chia-Network/chia-blockchain.git -b latest
cd chia-blockchain

# This installs compatible Python modules
sh install.sh
. ./activate

# If you want to debug/develop GUI app, try to install from source
# This installs supported version NodeJS/npm and npm dependencies.
sh install-gui.sh

# To open GUI app, run the following command
bash start-gui.sh

Update from source

*This instruction is for MacOS, Ubuntu, CentOS, RedHat, WSL2, Amazon Linux 2 and possibly *NIX like OSes.
To Update/Upgrade from the previous version

cd chia-blockchain
. ./activate
chia stop -d all
deactivate
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

git status

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

sh install.sh

. ./activate

chia init

# The GUI requires you have windowing system installed.
# You can not install and run the GUI as root
cd chia-blockchain-gui
git fetch
cd ..
chmod +x ./install-gui.sh
./install-gui.sh

# Run the GUI app
bash start-gui.sh

Testnets

To join a testnet, follow the instructions on the How to Connect to the Testnet article.

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/testnet10 chia init. An easier way to do this is to run export CHIA_ROOT="~/.chia/testnet10" so that all commands will use testnet10 instead of mainnet. If you're using a version above 1.2.11 (currently in beta), you can update all config values to the testnet values by running chia configure -t true.