Polars

Warnings

• breaking No row index. Polars has no implicit integer index like pandas. df.iloc[0] does not exist. Operations that depend on row position use row_index() or slice().
  Fix: Use df.row(0) for a single row as tuple, df[0] for first row as DataFrame, or df.head(1). Add explicit index with df.with_row_index('idx') if needed.
• breaking DataFrames are immutable. Item assignment df['col'] = ... raises TypeError. This is the most common error for pandas users.
  Fix: Use df.with_columns(pl.lit(value).alias('col')) or df.with_columns(expr.alias('new_col')).
• breaking groupby renamed to group_by in 0.19. Extremely common in LLM-generated code — groupby is in the vast majority of tutorials prior to 2024.
  Fix: Replace df.groupby(...) with df.group_by(...)
• breaking apply() renamed to map_elements() for element-wise UDFs, and map_batches() for Series-level UDFs. apply was removed in 1.0.
  Fix: Replace .apply(fn) with .map_elements(fn, return_dtype=pl.String) for row-wise UDFs. Always specify return_dtype to avoid schema inference overhead.
• breaking pl.count() deprecated and removed — used to count all rows including nulls. Replaced by pl.len().
  Fix: Replace pl.count() with pl.len(). For non-null count of a column: pl.col('x').count().
• breaking df.write_json() changed in 1.0: now only writes row-oriented JSON. The row_oriented and pretty parameters removed. Old JSON format (column-oriented) was used by read_json() — now use serialize()/deserialize() for that.
  Fix: For serialization round-trips: df.serialize(format='json') / pl.DataFrame.deserialize(). For standard row JSON: df.write_json().
• breaking LazyFrame.schema, .columns, .dtypes are now properties that emit PerformanceWarning — accessing them triggers schema resolution which can be expensive in complex lazy pipelines.
  Fix: Use lf.collect_schema() which returns a Schema object. Access columns via lf.collect_schema().names().
• gotcha Lazy execution does not run until .collect() is called. Forgetting .collect() returns a LazyFrame, not a DataFrame — printing it shows the query plan, not data.
  Fix: Always call .collect() at the end of a lazy chain: pl.scan_csv('f.csv').filter(...).collect()
• gotcha map_elements() (formerly apply) is always slow — it breaks out of Rust into Python for each element. For any operation with a native Polars expression, use the expression API instead.
  Fix: Use native expressions (pl.col('x').str.split(), .dt.year(), arithmetic, etc.) instead of map_elements wherever possible.

Install

• pip install polars Core (zero dependencies)
• pip install polars[all] All optional extras (pandas, numpy, pyarrow, excel, etc.)
• pip install polars[rt64] 64-bit row index (for >4.2 billion rows)
• pip install polars[rtcompat] Old CPU / Rosetta compatibility build (no AVX)

Imports

• polars

  import polars as pl
  
  df = pl.DataFrame({'a': [1, 2, 3], 'b': ['x', 'y', 'z']})
  result = df.filter(pl.col('a') > 1).select(['a', 'b'])

  Polars DataFrames are immutable. Use with_columns() for derived columns, not item assignment.
• group_by

  df.group_by('col').agg(pl.col('val').sum())

  groupby was renamed to group_by. LLM training data is full of the old name.

Quickstart

Eager and lazy execution patterns. Always prefer lazy (scan_*) for large files.

import polars as pl

# Eager execution
df = pl.DataFrame({
    'name': ['Alice', 'Bob', 'Charlie'],
    'score': [85, 92, 78],
    'dept': ['eng', 'eng', 'mkt']
})

result = (
    df
    .filter(pl.col('score') > 80)
    .group_by('dept')
    .agg(pl.col('score').mean().alias('avg_score'))
    .sort('avg_score', descending=True)
)

# Lazy execution (preferred for large data)
lazy_result = (
    pl.scan_csv('data.csv')
    .filter(pl.col('score') > 80)
    .group_by('dept')
    .agg(pl.col('score').mean())
    .collect()  # execute
)