PyLibcuDF (CUDA 12)

Common errors

• ImportError: libcudf.so: cannot open shared object file: No such file or directory

  cause The `pylibcudf` library cannot find its underlying C++ shared library. This often indicates a missing or incorrectly configured CUDA environment, or an ABI mismatch (e.g., trying to run a CUDA 12 compiled library on a system with only CUDA 11 libraries).
  fix Verify that CUDA Toolkit 12.x is properly installed and its library paths are in your `LD_LIBRARY_PATH`. If your system has CUDA 11, consider installing `pylibcudf-cu11` instead of `pylibcudf-cu12`.

• AttributeError: 'DataFrame' object has no attribute 'apply_chunks'

  cause You are attempting to use a method (`apply_chunks`, `apply_rows`, `apply_grouped`) that has been removed from the `cudf` API in recent versions.
  fix These methods were removed in `v25.10.00` and `v25.12.00` after deprecation. Refactor your code to use alternative `cudf` APIs, UDFs, or other optimized functions that have replaced their functionality.

• pyarrow.lib.ArrowInvalid: pyarrow_version < 19 is not supported

  cause Your installed PyArrow version is older than the minimum required by `cudf` v26.04.00 and later.
  fix Upgrade your PyArrow library: `pip install 'pyarrow>=19'`.

• RuntimeError: CUDA driver version is insufficient for CUDA runtime version

  cause The installed NVIDIA GPU driver is too old to support the CUDA Runtime version that `pylibcudf-cu12` was built against (CUDA 12).
  fix Update your NVIDIA GPU drivers to a version compatible with CUDA Toolkit 12.x. Refer to NVIDIA's CUDA Toolkit documentation for driver compatibility matrices.

Warnings

• breaking Starting with v26.04.00, `pylibcudf` (and by extension `cudf`) requires PyArrow version 19 or higher. Earlier versions will lead to import or runtime errors.
  Fix: Upgrade PyArrow: `pip install 'pyarrow>=19'`
• breaking The `DataFrame.apply_chunks`, `Groupby.apply_grouped`, and `DataFrame.apply_rows` methods have been removed. They were deprecated in earlier versions (v25.10.00) and removed in v25.12.00.
  Fix: Review `cudf` migration guides for alternative approaches to custom row/chunk-wise operations. Often, these can be replaced by UDFs (User Defined Functions) or other optimized `cudf` methods.
• gotcha The `pylibcudf-cu12` package is specifically compiled for CUDA Toolkit 12.x. Installing this package on a system with CUDA 11.x (or no CUDA toolkit) will likely result in `ImportError` or runtime failures due to ABI incompatibility.
  Fix: Ensure your system has CUDA Toolkit 12.x installed and configured correctly. If you need CUDA 11.x, install `pylibcudf-cu11` instead.
• breaking In v25.08.00, `cudf` dropped support for CUDA 11 usages. This means that if you're upgrading from a significantly older `cudf` version and still using CUDA 11, you will encounter issues.
  Fix: Upgrade your CUDA Toolkit to version 12.x and install the corresponding `pylibcudf-cu12` package.
• breaking The C++ function `cudf::get_current_device_resource` was removed in v26.02.00. While a C++ change, it could affect custom extensions or deep integrations relying on this.
  Fix: If custom C++ code or extensions use this, they will need to be updated to use alternative resource management approaches, e.g., direct `rmm` usage.

Install

• pip install pylibcudf-cu12 Recommended installation for CUDA 12

Imports

• cudf

  import cudf

  While 'pylibcudf' is the binding library, users typically interact with the higher-level 'cudf' API.

Quickstart

This quickstart demonstrates how to create a basic `cudf.DataFrame` and perform a simple element-wise operation, showcasing the primary entry point for using the library.

import cudf
import numpy as np

# Create a cuDF DataFrame from a dictionary
data = {'col1': np.random.rand(10), 'col2': np.arange(10)}
gdf = cudf.DataFrame(data)
print("Original DataFrame:")
print(gdf)

# Perform a simple operation
gdf['col3'] = gdf['col1'] * 2
print("\nDataFrame after operation:")
print(gdf)