Skip to main content
>>
>>
Version: v1.6.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.

note

With the release of Taichi v1.6.0, a comprehensive build environment preparation script (aka. build.py or ti-build) has been introduced. This script significantly simplifies the process of configuring a suitable build or development environment.

This guide will focus on the build.py approach. If you prefer to use the conventional method, you can refer to the previous Developer Installation document.

Prerequisites

CategoryPrerequisites
Linux distributionAnything recent enough, e.g. Ubuntu 20.04
Python3.6+, with a usable pip(python3-pip package on Ubuntu)
Clang++Clang++ >= 10, Clang++ 15 is recommended.
libstdc++-xx-devRun apt install libstdc++-10-dev, or just install g++.

Install Compiler

Taichi supports building from source with Clang++ >= 10.0 and MSVC from VS2022.

For macOS developers, it is recommended to use AppleClang, which comes with the Command Line Tools for Xcode. You can install them by running xcode-select --install. Alternatively, you can also install Xcode.app from the Apple Store.

For Linux developers, it is recommended to install Clang using the package manager specific to your operating system. On Ubuntu 22.04, running sudo apt install clang-15 should be sufficient. For older Ubuntu distributions to use a newer version of Clang, please follow the instructions on official LLVM Debian/Ubuntu Nightly Packages.

For Windows developers, if none of the VS2022 editions are installed, build.py will automatically start a VS2022 BuildTools installer for you.

Install LLVM

Install pre-built, customized LLVM binaries

build.py will automatically download and setup a suitable version of pre-built LLVM binaries.

Alternatively, build LLVM from source

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

To actually use the compiled LLVM binaries, replace the LLVM folder in the cache directory of build.py (open with ./build.py cache) with your own version.

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

Vulkan SDK is required to debug Taichi's Vulkan backend. build.py will automatically download and setup a suitable version of Vulkan SDK.

On Windows, Vulkan SDK requires elevated privileges to install (the installer would set several machine scope environement variables).

Ensure a working Vulkan SDK

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

  2. 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, and build.py won't setup Vulkan SDK for you).

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

  3. Check if the SDK is properly installed: Run vulkaninfo in the build shell:

    ./build.py --shell
    vulkaninfo

Build Taichi from source

  1. Clone the Taichi repo recursively and build1:
git clone --recursive https://github.com/taichi-dev/taichi

cd taichi

# Customize with your own needs
export TAICHI_CMAKE_ARGS="-DTI_WITH_VULKAN:BOOL=ON -DTI_WITH_CUDA:BOOL=ON"

# Uncomment if you want to use a different compiler
# export CC=/path/to/clang
# export CXX=/path/to/clang++

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

# This would drop into a shell with complete build environment,
./build.py --shell

# and then you could install Taichi in development mode
python3 setup.py develop
note

Alternatively, you could build a wheel file ready for install if you don't care about the convenience provided by python develop install:

./build.py
ls dist/*.whl

  1. 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, ./build.py --shell and python setup.py develop is recommended for you as a developer and ./build.py is more for end users. The difference is:

  • The python setup.py develop command does not actually install anything but only symbolically links the source code to the deployment directory.
  • The ./build.py command builds a wheel suitable for shipping so that you need to rerun the command and install the wheel every time the source code is modified.

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.

List of TAICHI_CMAKE_ARGS

FlagDescriptionDefault
BUILD_WITH_ADDRESS_SANITIZERBuild with clang address sanitizerOFF
TI_BUILD_EXAMPLESBuild the C++ examplesON
TI_BUILD_RHI_EXAMPLESBuild the Unified Device API examplesOFF
TI_BUILD_TESTSBuild the C++ testsOFF
TI_WITH_AMDGPUBuild with the AMDGPU backendOFF
TI_WITH_BACKTRACEUse backward-cpp to print out C++ stack trace upon failureOFF
TI_WITH_CUDABuild with the CUDA backendON
TI_WITH_CUDA_TOOLKITBuild with the CUDA toolkitOFF
TI_WITH_C_APIBuild Taichi runtime C-API libraryON
TI_WITH_DX11Build with the DX11 backendOFF
TI_WITH_DX12Build with the DX12 backendOFF
TI_WITH_GGUIBuild with GGUIOFF
TI_WITH_GRAPHVIZGenerate dependency graphs between targetsOFF
TI_WITH_LLVMBuild with LLVM backendsON
TI_WITH_METALBuild with the Metal backendON
TI_WITH_OPENGLBuild with the OpenGL backendON
TI_WITH_PYTHONBuild with Python language bindingON
TI_WITH_STATIC_C_APIBuild static Taichi runtime C-API libraryOFF
TI_WITH_VULKANBuild with the Vulkan backendOFF
USE_LLDUse lld (from llvm) linkerOFF
USE_MOLDUse mold (A Modern Linker)OFF
USE_STDCPPUse -stdlib=libc++OFF

Design goals, behaviors and usage of build.py

Created to be dead simple

Setting up an appropriate development environment for an unfamiliar project can be quite challenging. Therefore, build.py has been created to eliminate this friction. If you find any aspect of the environment configuration process to be 'too manual' or suffered to progress, it is considered a bug. Please report such issues on GitHub.

Designed to be minimally intrusive

Nearly all the dependencies of build.py and Taichi are explicitly placed at the cache folder, which can be opened by:

./build.py cache

Or you can find it at:

OSCache Folder Location
Linux && macOS~/.cache/ti-build-cache
Windows%LocalAppData%\ti-build-cache

A typical cache dir will contain sub folders below:

Sub FolderPurposeCode Responsible
bootstrapContains Python packages used by build.py itselfbootstrap.py
depsDownloaded external dependencies, before extract/installdep.py
llvm15Managed pre-built LLVM binariesllvm.py
mambaforgeManaged conda environment dedicated to build / develop Taichipython.py
sccacheCompile cachesccache.py
vulkan-1.x.xxx.xVulkan SDK locationvulkan.py

The whole cache folder can be safely removed.

build.py operates without the need for any third-party libraries to be installed, the requirements will be handled by its bootstrapping process.

note

On Debian/Ubuntu systems, apt install python3-pip is required.

Behaviors considered intrusive

  1. On Ubuntu systems, there's an attempt to install missing development libraries at ospkg.py by invoking sudo apt install libxxxx-dev if a terminal is detected. It can be skipped by telling apt not to install them.

  2. Installing Vulkan SDK on Windows requires elevated privileges, and the installer will set several machine scoped environment variables (VULKAN_SDK and VK_SDK_PATH).

Choose your desired Python version, or use your own Python environment.

By default, build.py assumes that the same Python version used to invoke it will also be used for building Taichi. build.py will then create an isolated Python environment and use it for all the subsequent Python related tasks. To use a different version, please specify the desired version via --python option:

# Build a wheel
./build.py --python=3.10

# Or enter development shell
./build.py --python=3.10 --shell

If you prefer to manage Python environments yourself, you could specify --python=native, and build.py will not attempt to use a managed Python environment.

# Use your own conda
conda activate my-own-conda-env

# Build a wheel
./build.py --python=native

# Or enter development shell
./build.py --python=native --shell

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.

Workaround

Run the following commands to enter development shell:

./build.py --shell

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?

Was this helpful?