Install & Compatibility
Where this runs
tested against v1.33.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.8s · import 0.344s · 145MB
143MB installed
● package 143MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
polars
✓ import polars as pl
The standard and recommended import alias.
This quickstart demonstrates creating a Polars DataFrame, filtering rows based on a condition, grouping data by a categorical column, aggregating results (mean and count), and finally sorting the output. It showcases basic eager DataFrame operations.
import polars as pl
# Create a DataFrame
df = pl.DataFrame(
{
"name": ["Alice", "Bob", "Charlie", "David", "Eve"],
"age": [25, 30, 35, 28, 22],
"city": ["New York", "London", "Paris", "New York", "London"],
"score": [90, 85, 92, 78, 95],
}
)
# Perform some operations: filter and group by city, then calculate average score
result = (
df.filter(pl.col("age") > 25)
.group_by("city")
.agg(
pl.col("score").mean().alias("average_score"),
pl.col("name").count().alias("num_people"),
)
.sort("average_score", descending=True)
)
print("Original DataFrame:\n", df)
print("\nProcessed Result:\n", result)
Debug
Known issues
gotchaThe `polars-lts-cpu` package is distinct from the main `polars` package. `polars-lts-cpu` provides a CPU-only, long-term support version that often trails the latest features and versions of the main `polars` package. Installing the wrong package can lead to unexpected features, performance, or dependencies.fixBe explicit about which Polars package you intend to install. Use `polars-lts-cpu` for stable, CPU-only environments. Use `polars` (and potentially its extras like `polars[pyarrow]`) for the latest features and potentially GPU support.
affects: All `polars-lts-cpu` versions.
breakingPolars strongly differentiates between eager (DataFrame) and lazy (LazyFrame) execution. Operations on a `DataFrame` are executed immediately, while `LazyFrame` operations are chained and only computed upon calling `.collect()`. Mixing these paradigms or expecting lazy behavior from an eager DataFrame is a common source of error.fixUnderstand the Polars execution model. For complex pipelines, convert your DataFrame to a LazyFrame using `.lazy()` and call `.collect()` at the end of the chain to trigger computation. E.g., `df.lazy().filter(...).group_by(...).collect()`.
affects: All Polars versions.
gotchaPolars is highly optimized to avoid unnecessary data copies, leading to 'view' semantics for many operations. This can surprise users accustomed to libraries like Pandas, where operations often create implicit copies. Modifying data derived from a view might inadvertently affect the original data if not handled carefully.fixIf an independent copy of a DataFrame or Series is needed before modification, explicitly create one using the `.clone()` method (e.g., `df.clone()`).
affects: All Polars versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'polars-lts-cpu'
The `polars-lts-cpu` Python package provides the `polars` module, so it should always be imported using `import polars` and not `import polars-lts-cpu`.
fixUse `import polars as pl` in your Python code after installing `polars-lts-cpu`.
RuntimeWarning: Missing required CPU features. The following required CPU features were not detected: avx, avx2, fma. Continuing to use this version of Polars on this processor will likely result in a crash.
The standard `polars` package is compiled with optimizations requiring modern CPU features (like AVX2), and this warning indicates your current CPU lacks them.
fixInstall the `polars-lts-cpu` package, which provides a build compatible with older CPUs: `pip install polars-lts-cpu` (after uninstalling any existing `polars` package).
polars.exceptions.ColumnNotFoundError: <column_name>
You are attempting to select or operate on a column with a name (`<column_name>`) that does not exist in the DataFrame or LazyFrame.
fixVerify the exact column name (including case sensitivity) using `df.columns` or `df.schema` and correct your code to use an existing column name.
polars.exceptions.ComputeError: schema lengths differ
When using `pl.concat` to vertically combine DataFrames, Polars by default expects all input DataFrames to have identical schemas (same columns in the same order and types). This error occurs when the schemas do not match.
fixTo concatenate DataFrames with different columns, use the `how='diagonal'` argument in `pl.concat`, which will create a union of all columns and fill missing values with `null`. Example: `pl.concat([df1, df2], how='diagonal')`.
ImportError: cannot import name 'POLARS_STORAGE_CONFIG_KEYS' from 'polars.io.cloud._utils'
This error typically occurs when both the `polars` and `polars-lts-cpu` packages are installed in the same environment at different versions, leading to conflicting Python source files.
fixUninstall both packages, then reinstall only the desired one: `pip uninstall polars polars-lts-cpu` followed by `pip install polars-lts-cpu` (or `pip install polars` if you don't need the LTS version).
Upgrade
Version history
1.33.1latest on PyPI · released Sep 9, 2025
Audit
Dependencies
pyarrowoptionalOften used for optimized I/O operations (e.g., Parquet, IPC, Feather) and better interoperability with other data tools.