Skip to main content
Version: v1.5.0

Developer Installation

Target audience

Developers who are interested in the compiler, computer graphics, or high-performance computing, and would like to contribute new features or bug fixes to the Taichi programming language.

IMPORTANT

This installation guide is NOT intended for end users who only wish to do simulation or high performance numerical computation. We recommend that end users install Taichi via pip install taichi. There is no need for you to build Taichi from source.

See the Get Started for more information on quickly setting up Taichi for end users.

Introduction

This installation guide covers the following:

note

Installation instructions vary depending on which operating system (OS) you are using. Choose the right OS or platform before you proceed.

Prerequisites

CategoryPrerequisites
OSmacOS / Ubuntu / Arch Linux / Other Linux distributions
Python3.7/3.8/3.9/3.10 We recommend installing Python from Miniforge conda if you are on a MacBook with M1 chip.
Clang++Clang++ >8
LLVM15.0.4 (Taichi customized version)
Command line tools for XcodeFor macOS users only: xcode-select --install

Install Clang

Taichi supports building from source with any clang compiler greater than version 8.0. Install one from your favorite package tool for the operating system. For example, you can use apt on Ubuntu, brew on macOS, and so on.

Install LLVM

Install pre-built, customized LLVM binaries

We provide pre-built, customized LLVM 15 binaries.

  1. Download and install customized binaries from the following list per your system environment:
  1. Configure environment variable:
  1. Set LLVM_DIR environment variable:

    echo "export LLVM_DIR=<PATH_TO_LLVM_FOLDER>" >>  ~/.bashrc
  2. Update your path for the remainder of the session:

    source ~/.bashrc
Build LLVM 15.0.0 from source

We provide instructions here if you need to build LLVM 15.0.0 from source.

wget https://github.com/llvm/llvm-project/archive/refs/tags/llvmorg-15.0.5.tar.gz

tar zxvf llvmorg-15.0.5.tar.gz

cd llvm-project-llvmorg-15.0.5/llvm

mkdir build

cd build

cmake .. -DLLVM_ENABLE_RTTI:BOOL=ON -DBUILD_SHARED_LIBS:BOOL=OFF -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD="X86;NVPTX" -DLLVM_ENABLE_ASSERTIONS=ON -DLLVM_ENABLE_TERMINFO=OFF

# If you are building on Apple M1, use -DLLVM_TARGETS_TO_BUILD="AArch64".

# If you are building on NVIDIA Jetson TX2, use -DLLVM_TARGETS_TO_BUILD="ARM;NVPTX"

# If you are building for a PyPI release, add -DLLVM_ENABLE_Z3_SOLVER=OFF to reduce the library dependency.

make -j 8

sudo make install

# Check your LLVM installation

llvm-config --version # You should get 15.0.5

Install optional dependencies

CUDA is NVIDIA's answer to high-performance computing. Taichi has implemented a backend based on CUDA 10.0.0+. Vulkan is a next-generation, cross-platform API, open standard for 3D graphics and computing. Taichi has added a Vulkan backend as of v0.8.0.

This section provides instructions on installing these two optional dependencies.

Install CUDA

This section works for you if you have a Nvidia GPU supporting CUDA. Note that the required CUDA version is 10.0+.

To install CUDA:

  1. Go to the official site to download the installer.

  2. Choose deb (local) as Installer Type.

  3. Check if CUDA is properly installed:

    nvidia-smi
Install Vulkan

You must install the Vulkan SDK in order to debug Taichi's Vulkan backend. To proceed:

  1. Go to Vulkan's SDK download page and follow the instructions for your OS.

  2. Check if environment variables VULKAN_SDK, PATH, LD_LIBRARY_PATH, and VK_LAYER_PATH are updated.

    The SDK for Ubuntu provides a setup-env.sh for updating these variables.

  3. Ensure that you have a Vulkan driver from a GPU vendor properly installed.

    On Ubuntu, check if a JSON file with a name corresponding to your GPU vendor is in: /etc/vulkan/icd.d/ or /usr/share/vulkan/icd.d/.

  4. Check if the SDK is properly installed: vulkaninfo.

  5. If the SDK is properly installed, add an environment variable TAICHI_CMAKE_ARGS with the value -DTI_WITH_VULKAN:BOOL=ON to enable the Vulkan backend: (Otherwise Vulkan backend is disabled by default when compiling from source.)

    export TAICHI_CMAKE_ARGS="$TAICHI_CMAKE_ARGS -DTI_WITH_VULKAN:BOOL=ON"

Build Taichi from source

  1. Clone the Taichi repo recursively and build1:

    git clone --recursive https://github.com/taichi-dev/taichi

    cd taichi

    python3 -m pip install --user -r requirements_dev.txt

    # export CXX=/path/to/clang++ # Uncomment if clang++ is not default compiler of the system. Note that clang is not acceptable due to requirements of some submodules.

    # export DEBUG=1 #Uncomment it if you wish to keep debug information.

    python3 setup.py develop --user
  2. Try out some of the demos in the examples/ folder to see if Taichi is properly installed. For example:

    python3 python/taichi/examples/simulation/mpm128.py
note

1Although the two commands work similarly, python setup.py develop is recommended for you as a developer and python setup.py installmore for end users. The difference is:

  • The develop command does not actually install anything but only symbolically links the source code to the deployment directory.
  • The install command deep copies the source code so that end users need to rerun the command every time they modify the source code.

The develop command serves the developers' needs better because edits to the Python files take effect immediately without the need to rerun the command. A rerun is needed only if you have modified the project's C extension or compiled files. See the Development Mode for more information.

Troubleshooting and debugging

Permission denied

Description

Gets a permission denied after python3 setup.py develop or python3 setup.py install.

Root cause

You were trying to install packages into the Python environment without write permission.

Workaround

  1. python3 setup.py develop --user or python3 setup.py install --user.
  2. Install Conda and use python from within the conda environment.

make fails to compile

Description

make fails to compile and reports fatal error: 'spdlog/XXX.h' file not found.

Root cause

You did not use the --recursive flag when cloning the Taichi repository.

Workaround

Run git submodule update --init --recursive --depth=1.

which python still returns the system's Python location

Description

which python still returns the system's Python location after Conda is installed.

Workaround

Run the following commands to activate Conda:

source <PATH_TO_CONDA>/bin/activate

conda init

Frequently asked questions

How can I get a fresh Taichi build?

  1. Clean up cache from your previous builds:

    python3 setup.py clean
  2. Uninstall the Taichi package from your Python environment:

  • python setup.py develop --uninstall, if you build Taichi using python setup.py develop.
  • pip uninstall taichi, if you build Taichi using python setup.py install.

What if I don't have wget on my macOS?

  1. Install Homebrew.

  2. Use Homebrew to install wget:

    brew install wget

Still have issues?