# nvidia/cudf architecture

> Architecture diagram of the GitHub repository nvidia/cudf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia/cudf
- Repository: https://github.com/nvidia/cudf

## Overview

cuDF is a GPU-accelerated tabular data platform. A typical workflow reads data into columnar tables, applies transformations and analytics such as null handling and groupby aggregation, then returns or writes results. The C++ libcudf API and CUDA implementations provide core operations; Python-facing products expose pandas-like, pandas-accelerator, and Polars interfaces, while Dask provides a documented distributed backend. The tree and README support these product boundaries, but sampled source is limited, so detailed Python-to-C++ bindings and Dask wiring are not asserted.

Main entry points: [`cpp/include/cudf/table/table.hpp`](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/table/table.hpp) (Tables and columns), [`cpp/include/cudf/io/parquet.hpp`](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/io/parquet.hpp) (File I/O APIs), [`python/cudf/cudf`](https://github.com/nvidia/cudf/tree/main/python/cudf/cudf) (cudf DataFrame), [`cpp/include/cudf/io/datasource.hpp`](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/io/datasource.hpp) (Input and output)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cudfpy["cudf DataFrame"]
  node_pandasaccel["cudf.pandas"]
  node_polars["cudf-polars GPU"]
  node_dask["Dask backend"]
  node_java["Java API<br/>[Aggregation.java]"]
end

subgraph group_core["Columnar core"]
  node_table["Tables and columns<br/>[table.hpp]"]
  node_column["Column model<br/>[column.hpp]"]
  node_memory["GPU memory"]
end

subgraph group_analytics["Data analytics"]
  node_ops["Column operations<br/>[binaryop.hpp]"]
  node_groupby["Groupby aggregation<br/>[groupby.hpp]"]
  node_join["Joins<br/>[join.hpp]"]
  node_strings["String operations<br/>[attributes.hpp]"]
  node_lists["Nested lists<br/>[combine.hpp]"]
  node_query["Query expressions<br/>[queryutils.py]"]
end

subgraph group_io["Data exchange"]
  node_ioapi["File I/O APIs<br/>[parquet.hpp]"]
  node_formats["CSV JSON ORC<br/>[csv.hpp]"]
  node_parquet["Parquet engine<br/>[reader.cpp]"]
  node_arrow["Arrow interchange<br/>[interop.hpp]"]
  node_storage["Input and output<br/>[datasource.hpp]"]
end

node_user(("Data user"))
node_files["Data files"]
node_cuda(("CUDA GPU"))

node_user -->|"uses"| node_cudfpy
node_user -->|"launches"| node_pandasaccel
node_user -->|"collects"| node_polars
node_user -.->|"uses"| node_dask
node_user -.->|"uses"| node_java
node_cudfpy -->|"reads and writes"| node_ioapi
node_pandasaccel -->|"accelerates I/O"| node_ioapi
node_polars -->|"executes plans"| node_table
node_dask -.->|"uses GPU backend"| node_table
node_java -.->|"accesses tables"| node_table
node_ioapi -->|"dispatches formats"| node_formats
node_ioapi -->|"calls reader/writer"| node_parquet
node_ioapi -->|"accesses sources"| node_storage
node_parquet -->|"reads and writes"| node_storage
node_formats -->|"accesses sources"| node_storage
node_files -->|"provides bytes"| node_storage
node_ioapi -->|"produces tables"| node_table
node_cudfpy -->|"operates on"| node_table
node_pandasaccel -->|"fallbacks to"| node_cudfpy
node_table -->|"organizes"| node_column
node_table -->|"transforms"| node_ops
node_table -->|"aggregates"| node_groupby
node_table -->|"joins"| node_join
node_table -->|"processes strings"| node_strings
node_table -->|"processes lists"| node_lists
node_cudfpy -->|"compiles queries"| node_query
node_query -->|"evaluates expressions"| node_table
node_column -->|"uses allocations"| node_memory
node_ops -->|"executes on"| node_cuda
node_groupby -->|"executes on"| node_cuda
node_join -->|"executes on"| node_cuda

click node_cudfpy "https://github.com/nvidia/cudf/tree/main/python/cudf/cudf"
click node_pandasaccel "https://github.com/nvidia/cudf/tree/main/python/cudf/cudf"
click node_polars "https://github.com/nvidia/cudf/blob/main/python/cudf_polars/cudf_polars/engine/default_singleton_engine.py"
click node_java "https://github.com/nvidia/cudf/blob/main/java/src/main/java/ai/rapids/cudf/Aggregation.java"
click node_table "https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/table/table.hpp"
click node_column "https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/column/column.hpp"
click node_memory "https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/utilities/memory_resource.hpp"
click node_ops "https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/binaryop.hpp"
click node_groupby "https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/groupby.hpp"
click node_join "https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/join/join.hpp"
click node_strings "https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/strings/attributes.hpp"
click node_lists "https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/lists/combine.hpp"
click node_query "https://github.com/nvidia/cudf/blob/main/python/cudf/cudf/utils/queryutils.py"
click node_ioapi "https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/io/parquet.hpp"
click node_formats "https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/io/csv.hpp"
click node_parquet "https://github.com/nvidia/cudf/blob/main/cpp/src/io/parquet/reader.cpp"
click node_arrow "https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/interop.hpp"
click node_storage "https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/io/datasource.hpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cudfpy,node_pandasaccel,node_polars,node_dask,node_java,node_user toneBlue
class node_table,node_column,node_memory toneAmber
class node_ops,node_groupby,node_join,node_strings,node_lists,node_query toneMint
class node_ioapi,node_formats,node_parquet,node_arrow,node_storage toneRose
class node_files,node_cuda toneIndigo
```

## Components

### User interfaces

- [cudf DataFrame](https://github.com/nvidia/cudf/tree/main/python/cudf/cudf): `python/cudf/cudf`
- [cudf.pandas](https://github.com/nvidia/cudf/tree/main/python/cudf/cudf): `python/cudf/cudf`
- [cudf-polars GPU](https://github.com/nvidia/cudf/blob/main/python/cudf_polars/cudf_polars/engine/default_singleton_engine.py): `python/cudf_polars/cudf_polars/engine/default_singleton_engine.py`
- **Dask backend**
- [Java API](https://github.com/nvidia/cudf/blob/main/java/src/main/java/ai/rapids/cudf/Aggregation.java): `java/src/main/java/ai/rapids/cudf/Aggregation.java`

### Columnar core

- [Tables and columns](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/table/table.hpp): `cpp/include/cudf/table/table.hpp`
- [Column model](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/column/column.hpp): `cpp/include/cudf/column/column.hpp`
- [GPU memory](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/utilities/memory_resource.hpp): `cpp/include/cudf/utilities/memory_resource.hpp`

### Data analytics

- [Column operations](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/binaryop.hpp): `cpp/include/cudf/binaryop.hpp`
- [Groupby aggregation](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/groupby.hpp): `cpp/include/cudf/groupby.hpp`
- [Joins](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/join/join.hpp): `cpp/include/cudf/join/join.hpp`
- [String operations](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/strings/attributes.hpp): `cpp/include/cudf/strings/attributes.hpp`
- [Nested lists](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/lists/combine.hpp): `cpp/include/cudf/lists/combine.hpp`
- [Query expressions](https://github.com/nvidia/cudf/blob/main/python/cudf/cudf/utils/queryutils.py): `python/cudf/cudf/utils/queryutils.py`

### Data exchange

- [File I/O APIs](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/io/parquet.hpp): `cpp/include/cudf/io/parquet.hpp`
- [CSV JSON ORC](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/io/csv.hpp): `cpp/include/cudf/io/csv.hpp`
- [Parquet engine](https://github.com/nvidia/cudf/blob/main/cpp/src/io/parquet/reader.cpp): `cpp/src/io/parquet/reader.cpp`
- [Arrow interchange](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/interop.hpp): `cpp/include/cudf/interop.hpp`
- [Input and output](https://github.com/nvidia/cudf/blob/main/cpp/include/cudf/io/datasource.hpp): `cpp/include/cudf/io/datasource.hpp`

### Other components

- **Data user**
- **Data files**
- **CUDA GPU**

## Connections

- Data user → cudf DataFrame: uses
- Data user → cudf.pandas: launches
- Data user → cudf-polars GPU: collects
- Data user → Dask backend: uses
- Data user → Java API: uses
- cudf DataFrame → File I/O APIs: reads and writes
- cudf.pandas → File I/O APIs: accelerates I/O
- cudf-polars GPU → Tables and columns: executes plans
- Dask backend → Tables and columns: uses GPU backend
- Java API → Tables and columns: accesses tables
- File I/O APIs → CSV JSON ORC: dispatches formats
- File I/O APIs → Parquet engine: calls reader/writer
- File I/O APIs → Input and output: accesses sources
- Parquet engine → Input and output: reads and writes
- CSV JSON ORC → Input and output: accesses sources
- Data files → Input and output: provides bytes
- File I/O APIs → Tables and columns: produces tables
- cudf DataFrame → Tables and columns: operates on
- cudf.pandas → cudf DataFrame: fallbacks to
- Tables and columns → Column model: organizes
- Tables and columns → Column operations: transforms
- Tables and columns → Groupby aggregation: aggregates
- Tables and columns → Joins: joins
- Tables and columns → String operations: processes strings
- Tables and columns → Nested lists: processes lists
- cudf DataFrame → Query expressions: compiles queries
- Query expressions → Tables and columns: evaluates expressions
- Column model → GPU memory: uses allocations
- Column operations → CUDA GPU: executes on
- Groupby aggregation → CUDA GPU: executes on
- Joins → CUDA GPU: executes on