{"id":7361,"library":"libcudf-cu12","title":"cuDF - GPU Dataframe (C++)","description":"`libcudf-cu12` is the underlying C++ library for cuDF, a GPU-accelerated DataFrame library for Python, part of the NVIDIA RAPIDS ecosystem. It enables pandas-like data manipulation directly on the GPU, leveraging CUDA for high performance. This PyPI meta-package primarily serves as a runtime dependency that transitively pulls in the Python `cudf-cu12` package. cuDF follows a rapid monthly release cadence (YYYY.MM.patch), consistently introducing new features and breaking changes. The current stable version is `26.4.0`.","status":"active","version":"26.4.0","language":"en","source_language":"en","source_url":"https://github.com/rapidsai/cudf","tags":["gpu","dataframe","rapids","cuda","data-science","high-performance","etl"],"install":[{"cmd":"pip install libcudf-cu12","lang":"bash","label":"Install libcudf-cu12 (for CUDA 12)"}],"dependencies":[{"reason":"This meta-package primarily installs cudf-cu12, which provides the Python API.","package":"cudf-cu12","optional":false},{"reason":"Critical for data interchange; strict version compatibility with cuDF is required.","package":"pyarrow","optional":false},{"reason":"Essential for underlying GPU array operations, must match CUDA version.","package":"cupy-cuda12x","optional":false}],"imports":[{"note":"`libcudf-cu12` is a meta-package that installs `cudf-cu12`, which provides the `cudf` module for Python usage. Do not attempt to import `libcudf` directly.","wrong":"import libcudf","symbol":"cudf","correct":"import cudf"},{"symbol":"DataFrame","correct":"import cudf\ngdf = cudf.DataFrame(...)"}],"quickstart":{"code":"import cudf\nimport numpy as np\n\n# Create a cuDF DataFrame directly on the GPU\ndata = {\n    'col1': np.random.rand(10),\n    'col2': np.random.randint(0, 100, 10)\n}\ngdf = cudf.DataFrame(data)\n\nprint(\"cuDF DataFrame head:\")\nprint(gdf.head())\nprint(f\"\\nMean of col1: {gdf['col1'].mean().item()}\")","lang":"python","description":"This quickstart demonstrates how to create a basic cuDF DataFrame and perform a simple aggregation, showcasing its pandas-like API for GPU data manipulation."},"warnings":[{"fix":"Thoroughly review release notes on the GitHub repository (`github.com/rapidsai/cudf/releases`) for specific version updates and migration guides. Pin exact versions of `cudf-cuXX` and its core dependencies (`cupy-cudaXX`, `pyarrow`) to ensure stability.","message":"cuDF introduces frequent breaking changes with its monthly release cycle, affecting API signatures (e.g., `DataFrame.apply_chunks` removal), internal behaviors, and default arguments. Examples include changes to partitioning APIs and removal of resource management functions.","severity":"breaking","affected_versions":"All major versions (e.g., v25.10.00, v25.12.00, v26.02.00, v26.04.00)."},{"fix":"Always ensure `pyarrow` and `cupy-cudaXX` versions precisely match the `cudf-cuXX` requirements specified in the `cudf` documentation, PyPI dependencies, or `conda` environment. Use `pip show cudf-cu12` to inspect required distributions.","message":"Strict compatibility requirements exist for `pyarrow`, `cupy-cudaXX`, and the underlying CUDA Toolkit. Mismatched versions are a common source of runtime errors, unexpected behavior, and performance issues, especially after minor cuDF updates. For `v26.04.00`, `pyarrow 19` is required.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Migrate your code to use the recommended alternative APIs as documented in the official cuDF documentation or detailed in the respective release notes. Avoid using experimental or preview features in production without careful testing.","message":"Several APIs, including specific `nvtext` functions (`byte_pair_encoding`), `DataFrame.apply_rows`, `DataFrame.apply_chunks`, and certain `cudf::round` overloads for float types, have been deprecated or removed in recent versions.","severity":"deprecated","affected_versions":"v25.08.00, v25.10.00, v26.04.00 and later."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify `cudf-cu12` is present in your environment: `pip list | grep cudf`. If missing or an incorrect version is installed, try re-installing it directly: `pip install --upgrade --no-deps cudf-cu12` or `pip install cudf-cu12==<VERSION>` matching your CUDA version.","cause":"The Python `cudf` package is not correctly installed or accessible in the environment, even if `libcudf-cu12` (the C++ runtime meta-package) is present. `libcudf-cu12` installs `cudf-cu12`, but sometimes installation or environment path issues occur.","error":"ModuleNotFoundError: No module named 'cudf' (or ImportError: cannot import name 'cudf' from 'cudf')"},{"fix":"Ensure an NVIDIA CUDA-capable GPU is installed, NVIDIA drivers are up-to-date, and the CUDA Toolkit is correctly installed and configured. Verify `nvidia-smi` runs successfully. Check if the `CUDA_VISIBLE_DEVICES` environment variable is set incorrectly, hiding the GPU.","cause":"The system lacks a compatible NVIDIA GPU, CUDA drivers are not correctly installed, or the environment is misconfigured to access the GPU. This indicates a fundamental issue with the CUDA setup.","error":"CUDA_ERROR_NO_DEVICE: no CUDA-capable device is detected"},{"fix":"Pin your `pyarrow` version to the one specifically required by your `cudf` installation. Check the `Requires-Dist` output of `pip show cudf-cu12` or refer to the `cudf` documentation for the exact `pyarrow` version compatible with your `cudf` release (e.g., `pip install pyarrow==<REQUIRED_VERSION>`).","cause":"An incompatibility between the installed `cudf` version and the `pyarrow` version. `cudf` has strict `pyarrow` requirements, and even minor mismatches can lead to type or schema validation failures during data conversion.","error":"PyArrowTypeError: Expected array of type Int64, got array of type Timestamp[ns]"},{"fix":"Ensure your `cupy-cudaXX` package version precisely matches your system's CUDA Toolkit version (e.g., `cupy-cuda12x` for CUDA 12.x). Verify that `cudf` and `cupy` are compatible. Restarting the Python kernel or environment can sometimes resolve transient GPU context issues.","cause":"This error often indicates a mismatch between the `cupy-cudaXX` package and the installed CUDA Toolkit, or a more fundamental issue with the GPU's context initialization or available resources.","error":"cupy.cuda.runtime.CUDARuntimeError: cudaErrorInitializationError: initialization error"}]}