Skip to main content
Version: v1.0.3

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.


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.


This installation guide covers the following:


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


OSmacOS / Ubuntu / Arch Linux / Other Linux distributions
Python3.6/3.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:



    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.


tar xvJf llvm-10.0.0.src.tar.xz

cd llvm-10.0.0.src

mkdir build

cd build


# 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:


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 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.)


Build Taichi from sourceโ€‹

  1. Clone the Taichi repo recursively and build1:

    git clone --recursive

    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 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/

1Although the two commands work similarly, python develop is recommended for you as a developer and python 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โ€‹


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


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

Permission deniedโ€‹


Gets a permission denied after python3 develop or python3 install.

Root cause

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


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

make fails to compileโ€‹


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.


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

which python still returns the system's Python locationโ€‹


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


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 clean
  2. Uninstall the Taichi package from your Python environment:

  • python develop --uninstall, if you build Taichi using python develop.
  • pip uninstall taichi, if you build Taichi using python 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?โ€‹