Skip to main content
Version: develop

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 and that 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++8 Clang++ <12
LLVM10.0.0 (Taichi customized version)
Command line tools for XcodeFor macOS users only: xcode-select --install

Install Clang

This Clang compiler is used to compile the Taichi device runtime. It is **not required** to use this compiler for the C++ compiler.
  1. Download Clang + LLVM 10.0.0 pre-built binary for Ubuntu 18.04.

  2. Update the environment variables TAICHI_CMAKE_ARGS and PATH:

    export TAICHI_CMAKE_ARGS="-DCMAKE_CXX_COMPILER=<PATH_TO_LLVM_FOLDER>/bin/clang++ $TAICHI_CMAKE_ARGS"

    export PATH=<PATH_TO_LLVM_FOLDER>/bin:$PATH
    NOTE

    Some Linux distributions may require additional packages to build Taichi. Keep an eye on the output of CMake when building from source.

Install LLVM

Install pre-built, customized LLVM binaries

We provide pre-built, customized LLVM binaries. For now, Taichi supports LLVM 10.0.0 only.

  1. Download and install customized binaries from the following list per your system environment:
  1. Configure environment variable:
  1. Add LLVM to your PATH variable:

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

    source ~/.bashrc
Build LLVM 10.0.0 from source

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

wget https://github.com/llvm/llvm-project/releases/download/llvmorg-10.0.0/llvm-10.0.0.src.tar.xz

tar xvJf llvm-10.0.0.src.tar.xz

cd llvm-10.0.0.src

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 10.0.0

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

llvm-as cannot be opened on macOS

Description

Gets an error message llvm-as can’t be opened because Apple cannot check it for malicious software on macOS.

Workaround

One-off: System Preferences > Security & Privacy > General > Allow anyway.

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?