/polars

name: polars
description: High-performance DataFrame library for Python ETL, analytics, and pandas migration. It supports expression-based data manipulation with lazy query optimization, parallel execution, streaming out-of-core processing, Arrow interoperability, and optional GPU execution.
license: https://github.com/pola-rs/polars/blob/main/LICENSE
allowed-tools: Read
compatibility: Requires Python 3.10+ for Polars 1.44.2. Install with uv pip install; optional extras enable Excel, database, cloud, pandas/NumPy, and GPU integrations.
metadata:
  version: "1.4"
  last-reviewed: "2026-10-01"
  upstream-version: "1.44.2"
  skill-author: K-Dense Inc.

Polars

Overview

Polars is a columnar DataFrame library for Python and Rust with Arrow interoperability. Work with Polars' expression-based API, lazy evaluation framework, and high-performance data manipulation capabilities for efficient data processing, pandas migration, and data pipeline optimization.

Reviewed against the official stable documentation and native Polars 1.44.2. Local regression tests cover the corrected APIs and scientific failure cases; cloud, GPU, BigQuery, and remote database recipes are illustrative and require provider setup. Fragments using undefined columns, paths, or `...` require adaptation to the dataset.

Quick Start

Installation and Basic Usage

Install the current stable Polars release verified during this refresh:

uv pip install "polars==1.44.2"

Install optional integrations only when needed:

uv pip install "polars[excel,database,fsspec,pandas,numpy]==1.44.2"

Basic DataFrame creation and operations:

import polars as pl

# Create DataFrame
df = pl.DataFrame({
    "name": ["Alice", "Bob", "Charlie"],
    "age": [25, 30, 35],
    "city": ["NY", "LA", "SF"]
})

# Select columns
df.select("name", "age")

# Filter rows
df.filter(pl.col("age") > 25)

# Add computed columns
df.with_columns(
    age_plus_10=pl.col("age") + 10
)

Core Concepts

Expressions

Expressions are the fundamental building blocks of Polars operations. They describe transformations on data and can be composed, reused, and optimized.

**Key principles:**

• Use `pl.col("column_name")` to reference columns
• Chain methods to build complex transformations
• Expressions are lazy and only execute within contexts (select, with_columns, filter, group_by)

**Example:**

# Expression-based computation
df.select(
    pl.col("name"),
    (pl.col("age") * 12).alias("age_in_months")
)

Lazy vs Eager Evaluation

**Eager (DataFrame):** Operations execute immediately

df = pl.read_csv("file.csv")  # Reads immediately
result = df.filter(pl.col("age") > 25)  # Executes immediately

**Lazy (LazyFrame):** Operations build a query plan, optimized before execution

lf = pl.scan_csv("file.csv")  # Builds a plan; schema inference can read the source
result = lf.filter(pl.col("age") > 25).select("name", "age")
df = result.collect()  # Now executes optimized query

**When to use lazy:**

• Working with large datasets
• Complex query pipelines
• When only some columns/rows are needed
• Performance is critical

**Benefits of lazy evaluation:**

• Automatic query optimization
• Predicate pushdown
• Projection pushdown
• Parallel execution

For detailed concepts, load `references/core_concepts.md`.

Common Operations

Select

Select and manipulate columns:

# Select specific columns
df.select("name", "age")

# Select with expressions
df.select(
    pl.col("name"),
    (pl.col("age") * 2).alias("double_age")
)

# Select all columns matching a pattern
df.select(pl.col("^.*_id$"))

Filter

Filter rows by conditions:

# Single condition
df.filter(pl.col("age") > 25)

# Multiple conditions (cleaner than using &)
df.filter(
    pl.col("age") > 25,
    pl.col("city") == "NY"
)

# Complex conditions
df.filter(
    (pl.col("age") > 25) | (pl.col("city") == "LA")
)

With Columns

Add or modify columns while preserving existing ones:

# Add new columns
df.with_columns(
    age_plus_10=pl.col("age") + 10,
    name_upper=pl.col("name").str.to_uppercase()
)

# Parallel computation (all columns computed in parallel)
df.with_columns(
    (pl.col("value") * 10).alias("value_times_10"),
    (pl.col("value") * 100).alias("value_times_100"),
)

Group By and Aggregations

Group data and compute aggregations:

# Basic grouping
df.group_by("city").agg(
    pl.col("age").mean().alias("avg_age"),
    pl.len().alias("count")
)

# Multiple group keys
df.group_by("city", "department").agg(
    pl.col("salary").sum()
)

# Conditional aggregations
df.group_by("city").agg(
    (pl.col("age") > 30).sum().alias("over_30")
)

For detailed operation patterns, load `references/operations.md`.

Aggregations and Window Functions

Aggregation Functions

Common aggregations within `group_by` context:

• `pl.len()` - count rows
• `pl.col("x").sum()` - sum values
• `pl.col("x").mean()` - average
• `pl.col("x").min()` / `pl.col("x").max()` - extremes
• `pl.first()` / `pl.last()` - first/last values

Window Functions with `over()`

Apply aggregations while preserving row count:

# Add group statistics to each row
df.with_columns(
    avg_age_by_city=pl.col("age").mean().over("city"),
    rank_in_city=pl.col("salary").rank().over("city")
)

# Multiple grouping columns
df.with_columns(
    group_avg=pl.col("value").mean().over("category", "region")
)

**Mapping strategies:**

• `group_to_rows` (default): Maps results back to rows; scalar aggregates broadcast.
• `explode`: Changes row layout/count; use in `select`, not alongside original rows.
• `join`: Joins grouped values back as lists; can consume substantial memory.

Data I/O

Supported Formats

Polars supports reading and writing:

• CSV, Parquet, JSON, Excel
• Databases (via connectors)
• Cloud storage (S3, Azure, GCS)
• Google BigQuery through its SDK or a supported d