Skip to main content

Python Pandas: How to Resolve "TypeError: cannot convert the series to class 'int'"

When working with pandas, the TypeError: cannot convert the series to <class 'int'> is a common error. It occurs when you pass an entire pandas Series (a DataFrame column) to a Python function that is designed to work on only a single, scalar value (like a single number or string). Functions like the built-in int() or float() do not know how to operate on a collection of values at once.

The solution is to use a method specifically designed for element-wise operations on a Series. This guide will walk you through the recommended .astype() method and other powerful alternatives like .apply() and list comprehensions.

Understanding the Error: Scalar vs. Series (Vector) Operations​

The core of this issue is the difference between a single value and a column of values:

  • Scalar: A single piece of data, like the Python float 3.6. The built-in int() function is designed to convert one scalar value at a time (e.g., int(3.6) returns 3).
  • Series (Vector): A one-dimensional array of values, which represents a column in a pandas DataFrame. For example, df['distance'] is a Series.

The TypeError is raised because a function like int() receives a Series object and does not know how to convert the entire collection into the single int it was expecting.

Reproducing the TypeError​

The error is easily triggered by applying the standard int() function directly to a DataFrame column.

Example of code causing the error:

import pandas as pd

df = pd.DataFrame({"distance": [3.6, 18.3, 21.5, 25.2]})

# Incorrect: int() expects a single value, not a Series.
df['int_distance'] = int(df['distance'])

Output:

Traceback (most recent call last):
  File "main.py", line 6, in <module>
    df['int_distance'] = int(df['distance'])
  File "/usr/lib/python3.8/site-packages/pandas/core/series.py", line 129, in wrapper
    raise TypeError(f"cannot convert the series to {converter}")
TypeError: cannot convert the series to <class 'int'>

The .astype() method is the standard, idiomatic, and most efficient way to cast an entire pandas Series to a different data type.

Solution:

import pandas as pd

df = pd.DataFrame({"distance": [3.6, 18.3, 21.5, 25.2]})

# ✅ Correct: Use the .astype() method to convert the entire column to integers.
df['integer_distance'] = df['distance'].astype(int)

print(df)
print(f"\nData type of the new column: {df['integer_distance'].dtype}")

Output:

   distance  integer_distance
0       3.6                 3
1      18.3                18
2      21.5                21
3      25.2                25

Data type of the new column: int64

This is the preferred solution for simple type conversions.

Solution 2: Use the .apply() Method​

The .apply() method is a more general tool that applies a given function to each element in a Series. It is very powerful for more complex transformations where a simple type cast is not enough.

Solution:

import pandas as pd
from datetime import datetime

# Example with a more complex function: converting timestamps
df = pd.DataFrame(
    {"created_ts": [1674195300, 1674196140, 1674196620]}
)

# ✅ Correct: Use .apply() to pass each timestamp to the conversion function.
df['date'] = df['created_ts'].apply(datetime.fromtimestamp)

print(df)

Output:

   created_ts                date
0  1674195300 2023-01-20 06:15:00
1  1674196140 2023-01-20 06:29:00
2  1674196620 2023-01-20 06:37:00

While you can use .apply(int), the .astype(int) method is optimized for type casting and is generally faster.

Solution 3: Use a List Comprehension​

A list comprehension is a highly readable and Pythonic way to perform the same element-wise operation. It creates a new list, which pandas then converts into a new Series.

Solution:

import pandas as pd

df = pd.DataFrame({"distance": [3.6, 18.3, 21.5, 25.2]})

# ✅ Correct: Iterate through the Series and apply int() to each value.
df['integer_distance'] = [int(value) for value in df['distance']]

print(df)

Output:

   distance  integer_distance
0       3.6                 3
1      18.3                18
2      21.5                21
3      25.2                25

For simple conversions, this can be as readable and performant as .apply().

Conclusion​

If you want to...The best solution is...
Change the data type of an entire column (e.g., float to int).Use the .astype() method. It is the most efficient and idiomatic pandas function for this task.
Apply a complex function to each element of a column.Use the .apply() method.
Use a clear, Pythonic alternative for element-wise operations.Use a list comprehension.

The TypeError: cannot convert the series to <class 'int'> is a clear signal that you are trying to use a scalar function on a vector (Series). By switching to a method designed for element-wise operations, you can easily resolve the error and perform your desired data transformation.

Table of Contents