Polars DataFrames and Series Guide

Polars is a fast and efficient DataFrame library for Python. It is designed to handle large datasets with ease. If you are new to Polars, understanding how to create DataFrames and Series is the first step. This guide will show you the simplest ways to build them. We will use clear examples and short code snippets. No fluff, just clean and readable content.

Before you begin, make sure you have Polars installed. If not, check out our guide on Install Polars in Python Step by Step. Once you have it, you can start creating data structures right away.

What is a Series in Polars?

A Series is a single column of data. It is like a list but with a data type. You can create a Series from a Python list, a NumPy array, or other sources. Polars Series are fast and memory-efficient.

To create a Series, use the pl.Series() function. You need to provide a name and the data. Here is a basic example:

import polars as pl

# Create a Series from a list
s = pl.Series("ages", [25, 30, 35, 40])
print(s)

shape: (4,)
Series: 'ages' [i64]
[
    25
    30
    35
    40
]

Notice the output shows the shape, name, and data type. The data type here is i64 (64-bit integer). You can also specify a dtype explicitly. This is useful when you need a specific type like float or string.

# Create a Series with explicit dtype
s2 = pl.Series("scores", [85.5, 90.0, 78.3], dtype=pl.Float64)
print(s2)

shape: (3,)
Series: 'scores' [f64]
[
    85.5
    90.0
    78.3
]

Series are the building blocks of DataFrames. You can combine multiple Series to form a DataFrame. But Polars also provides direct ways to create DataFrames from other data sources.

Creating a DataFrame from a Dictionary

The most common way to create a DataFrame in Polars is from a Python dictionary. The keys become column names, and the values become columns. Each value should be a list, array, or Series of the same length.

Use the pl.DataFrame() function. Here is an example:

import polars as pl

# Create a DataFrame from a dictionary
data = {
    "name": ["Alice", "Bob", "Charlie"],
    "age": [25, 30, 35],
    "city": ["New York", "London", "Paris"]
}
df = pl.DataFrame(data)
print(df)

shape: (3, 3)
┌─────────┬─────┬──────────┐
│ name    ┆ age ┆ city     │
│ ---     ┆ --- ┆ ---      │
│ str     ┆ i64 ┆ str      │
╞═════════╪═════╪══════════╡
│ Alice   ┆ 25  ┆ New York │
│ Bob     ┆ 30  ┆ London   │
│ Charlie ┆ 35  ┆ Paris    │
└─────────┴─────┴──────────┘

This creates a clean table with three columns. Polars automatically infers the data types. You can see the types in the header: str for strings, i64 for integers. This is very similar to pandas, but Polars is often faster. For a deeper comparison, read our article on Polars vs Pandas: Why Switch?.

Creating a DataFrame from a List of Dictionaries

Another common pattern is a list of dictionaries. Each dictionary represents a row. This is useful when data comes from APIs or JSON files.

Pass the list directly to pl.DataFrame(). Here is how:

# Create a DataFrame from a list of dicts
rows = [
    {"name": "Alice", "age": 25, "city": "New York"},
    {"name": "Bob", "age": 30, "city": "London"},
    {"name": "Charlie", "age": 35, "city": "Paris"}
]
df2 = pl.DataFrame(rows)
print(df2)

shape: (3, 3)
┌─────────┬─────┬──────────┐
│ name    ┆ age ┆ city     │
│ ---     ┆ --- ┆ ---      │
│ str     ┆ i64 ┆ str      │
╞═════════╪═════╪══════════╡
│ Alice   ┆ 25  ┆ New York │
│ Bob     ┆ 30  ┆ London   │
│ Charlie ┆ 35  ┆ Paris    │
└─────────┴─────┴──────────┘

The output is the same as before. Polars handles the conversion smoothly. This method is great for small datasets or when you need to build data on the fly.

Creating a DataFrame from Lists of Lists

Sometimes you have data in a nested list structure. For example, a list of rows, where each row is a list of values. In this case, you need to provide column names separately.

Use pl.DataFrame() with the columns parameter. Here is an example:

# Create a DataFrame from a list of lists
data = [
    ["Alice", 25, "New York"],
    ["Bob", 30, "London"],
    ["Charlie", 35, "Paris"]
]
columns = ["name", "age", "city"]
df3 = pl.DataFrame(data, schema=columns)
print(df3)

shape: (3, 3)
┌─────────┬─────┬──────────┐
│ name    ┆ age ┆ city     │
│ ---     ┆ --- ┆ ---      │
│ str     ┆ i64 ┆ str      │
╞═════════╪═════╪══════════╡
│ Alice   ┆ 25  ┆ New York │
│ Bob     ┆ 30  ┆ London   │
│ Charlie ┆ 35  ┆ Paris    │
└─────────┴─────┴──────────┘

Note the use of schema instead of columns. In Polars, you can use either, but schema is more flexible because it also allows you to specify dtypes. For example:

# Specify schema with dtypes
schema = {"name": pl.Utf8, "age": pl.Int32, "city": pl.Utf8}
df4 = pl.DataFrame(data, schema=schema)
print(df4)

shape: (3, 3)
┌─────────┬─────┬──────────┐
│ name    ┆ age ┆ city     │
│ ---     ┆ --- ┆ ---      │
│ str     ┆ i32 ┆ str      │
╞═════════╪═════╪══════════╡
│ Alice   ┆ 25  ┆ New York │
│ Bob     ┆ 30  ┆ London   │
│ Charlie ┆ 35  ┆ Paris    │
└─────────┴─────┴──────────┘

Notice the age column now has type i32 instead of i64. This gives you control over memory usage.

Creating a DataFrame from a NumPy Array

If you work with NumPy, you can easily convert arrays to Polars DataFrames. Use pl.from_numpy() or pass the array directly with column names.

Here is an example using pl.from_numpy():

import numpy as np
import polars as pl

# Create a NumPy array
arr = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
# Convert to Polars DataFrame
df_np = pl.from_numpy(arr, schema=["a", "b", "c"])
print(df_np)

shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 2   ┆ 3   │
│ 4   ┆ 5   ┆ 6   │
│ 7   ┆ 8   ┆ 9   │
└─────┴─────┴─────┘

You can also pass a 1D array as a single column. Just wrap it in a list or use pl.Series() first.

Creating a DataFrame from CSV or Other Files

Polars makes it easy to read data from files. Use pl.read_csv() for CSV files. This is often the first step in real projects.

# Read a CSV file into a DataFrame
df_csv = pl.read_csv("data.csv")
print(df_csv.head())

This is just a quick example. For more details, refer to the official Polars documentation. The key point is that Polars supports many formats including CSV, Parquet, JSON, and Excel.

Working with Null Values

Real-world data often has missing values. Polars handles nulls gracefully. You can create a Series or DataFrame with nulls using None or pl.Null.

# Create a Series with null values
s_null = pl.Series("values", [1, None, 3, None])
print(s_null)

shape: (4,)
Series: 'values' [i64]
[
    1
    null
    3
    null
]

Nulls are shown as null in the output. You can then use methods like drop_nulls() or fill_null() to clean your data.

Conclusion

Creating DataFrames and Series in Polars is straightforward. You can use dictionaries, lists, NumPy arrays, or files. The library is designed for speed and simplicity. Start with the dictionary method for most cases. Use lists of dictionaries for row-based data. And always check your data types with the schema parameter.

Polars is a powerful alternative to pandas. It offers better performance and a cleaner API. If you are just starting, practice with the examples above. Soon you will be handling large datasets with ease. For a complete setup guide, revisit Install Polars in Python Step by Step. Happy coding!