Build Python package from source

Source code

CatBoost source code is stored as a Git repository on GitHub at https://github.com/catboost/catboost/. You can obtain a local copy of this Git repository by running the following command from a command line interpreter (you need to have Git command line tools installed):

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

Later in this document $CATBOOST_SRC_ROOT refers to the root dir of the local working copy of the source code cloned from the GitHub CatBoost repository.

Dependencies and requirements

1. As CatBoost Python package has a native extension library as its' core build environment setup for CMake is required.

2. setuptools Python package, version 64.0+. Installed by default for Python < 3.12, an explicit installation is needed for Python 3.12+.

3. Other setup dependencies that can be formulated as python packages are listed in pyproject.toml's build-system.requires and in setup.py in standard setup_requires parameter and processed using standard Python tools.

   Note

   For some reason Python 3.12 fails to automatically resolve build/setup dependencies in a way that they are buildable so it is recommended to install the following packages using pip explicitly:
   - setuptools
   - wheel
   - jupyterlab (3.x, 4.x is not supported yet, see the relevant issue)
   - conan (2.4.1+, for revisions before 21a3f85 only conan 1.x with versions 1.62.0+ is supported)

4. For building CatBoost visualization widget bundled together with the python package (enabled by default) additional setup is required:

   1. Node.js installation with npm command accessible from the shell.
   2. rimraf Node.js package installed with npm's --global option (this way rimraf command will be accessible from the shell).
   3. yarn package manager, version from 1.x series, 1.22.10 or later. Installed with npm's --global option (this way yarn command will be accessible from the shell)
      An example command to install: npm install --global yarn@1.22.10.

   If you don't need CatBoost visualization widget support you can disable it's building and bundling with the CatBoost python package by passing --no-widget build/installation option.

5. Installation dependencies are listed in setup.py in standard install_requires parameter and processed using standard Python tools.

6. User-defined functions

   If you want to use custom metrics or objectives implemented in your own python code you should install numba package to speed up the code execution using JIT compilation.

   If you want to use custom metrics or objectives on GPUs with CUDA support you must install numba package for JIT compilation of CUDA code.
   Installation of numba-cuda package is also encouraged.
   CUDA itself (not only drivers) must be installed on machines where this code is executed.
   See numba CUDA support documentation for more details.

   These packages are not listed in package requirements that are installed automatically because they are not needed for other functionality.

Training or inference on CUDA-enabled GPUs requires NVIDIA Driver of version 450.80.02 or higher.

Building

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

Use Python's standard procedures:

Build the wheel distribution

python setup.py bdist_wheel <options>

Options can be listed by calling python setup.py bdist_wheel --help.

One important option is --prebuilt-extensions-build-root-dir=<path>. It allows to use already built binary _catboost extension shared library. See Build native artifacts. Set this option value to $CMAKE_BINARY_DIR.

The resulting wheel distribution will be created in dist/catboost-<version>-<...>.whl

Build the source distribution (sdist)

python -m build --sdist

The resulting source distribution will be created in dist/catboost-<version>.tar.gz file.

Other useful commands

• build_widget. Build CatBoost widget.

  python setup.py build_widget
  

  Useful if widget code remains unchanged but you want to rebuild other parts. Then run build_widget once and then in subsequent calls to bdist_wheel or other commands use --prebuilt-widget option.

Installation

Directly from the source directory

Builds in the process. So build environment setup for CMake is required.

python -m pip install . <options>

You can pass options to setup.py's install stage by using --install-option options like this:

python -m pip install . --install-option=--with-hnsw --install-option=--with-cuda=/usr/local/cuda-11

Create editable install

Builds in the process. So build environment setup for CMake is required.

python -m pip install --editable . <options>

You can pass options to setup.py's install stage by using --install-option options like this:

python -m pip install  --install-option=--with-hnsw --install-option=--with-cuda=/usr/local/cuda-11/ --editable .

Install from the built wheel

python -m pip install <path-to-wheel>

Install from the source distribution

Builds in the process. So build environment setup for CMake is required.

python -m pip install <path-to-sdist-tar.gz>