Build from source on Linux and macOS

Dependencies and requirements

The following packages are required for installation:

• python3
• python3-dev
• numpy
• pandas

The system compiler must be compatible with CUDA Toolkit if GPU support is required. Refer to the Supported Host Compilers section of the NVIDIA CUDA Compiler Driver NVCC documentation for more details. The required steps to change the system compiler depend on the OS.

Training on GPU requires NVIDIA Driver of version 418.xx or higher.

Building steps

To build the Python package from source on Linux and macOS:

1. Install the libc header files on macOS and Linux.

   Depending on the used OS:

   • macOS: xcode-select --install
   • Linux: Install the appropriate package (for example, libc6-dev on Ubuntu)

2. Clone the repository:

   git clone https://github.com/catboost/catboost.git
   

3. (Optionally) Volta GPU users are advised to precisely set the required NVCC compile flags in the default_nvcc_flags.make.inc configuration file. Removing irrelevant flags speeds up the compilation.

   Note

   CatBoost may work incorrectly with Independent Thread Scheduling introduced in Volta GPUs when the number of splits for features exceeds 32.

4. (Optionally) CUDA with compute capability 2.0 users must remove all lines starting with -gencode from the default_nvcc_flags.make.inc configuration file and add the following line instead:

   -gencode arch=compute_20,code=compute_20
   

5. Open the catboost/catboost/python-package/catboost directory from the local copy of the CatBoost repository.

6. Compile the packages using one of the following methods:

   • Use one of the Python versions provided by the ya make utility:

     ../../../ya make -r -DUSE_ARCADIA_PYTHON=no -DUSE_SYSTEM_PYTHON=<Python version> [optional parameters]
     

   • Use one of the Python versions installed on the machine:

     ../../../ya make -r -DUSE_ARCADIA_PYTHON=no -DOS_SDK=local -DPYTHON_CONFIG=<path to the required python-config> [optional parameters]
     

   Parameter	Description
   Parameters that define the Python version to use for compiling. Only one of the following blocks of options can be used at a time
   Use one of the Python versions provided by the ya make utility
   -DUSE_SYSTEM_PYTHON	The version of Python to use for compiling the package on machines without installed Python. The following Python versions are supported and can be defined as values for this parameter: 2.7 3.4 3.5 3.6
   Use one of the Python versions installed on the machine
   -DPYTHON_CONFIG	Defines the path to the configuration of an installed Python version to use for compiling the package. Value examples: python2-config for Python 2 python3-config for Python 3 /usr/bin/python2.7-config The configuration must be explicitly named python3-config to successfully build the package for Python 3. Manually redefine the following variables when encountering problems with the Python configuration: -DPYTHON_INCLUDE -DPYTHON_LIBRARIES -DPYTHON_LDFLAGS -DPYTHON_FLAGS -DPYTHON_BIN
   Optional parameters
   -DCUDA_ROOT	The path to CUDA. This parameter is required to support training on GPU.
   -DHAVE_CUDA=no	Disable CUDA support. This speeds up compilation. By default, the package is built with CUDA support if CUDA Toolkit is installed.
   -o	The directory to output the compiled package to. By default, the current directory is used.

   For example, the following command builds the package for Python 3 with training on GPU support:

   ../../../ya make -r -DUSE_ARCADIA_PYTHON=no -DOS_SDK=local -DPYTHON_CONFIG=python3-config -DCUDA_ROOT=/usr/local/cuda
   

   Note

   The required version of Xcode for building on macOS is specified on the NVIDIA site when downloading the CUDA toolkit.

7. Add the current directory to PYTHONPATH:

   cd ../; export PYTHONPATH=$PYTHONPATH:$(pwd)
   

Troubleshooting