Skip to main content
`Ctrl`+`K`

# pandas.to_numeric

pandas.to_numeric(arg, errors='raise', downcast=None, dtype_backend=<no_default>)

  Convert argument to a numeric type.

  If the input is already of a numeric dtype, the dtype will be preserved. For non-numeric inputs, the default return dtype is float64 or int64 depending on the data supplied. Use the downcast parameter to obtain other dtypes.

  Please note that precision loss may occur if really large numbers are passed in. Due to the internal limitations of ndarray, if numbers smaller than -9223372036854775808 (np.iinfo(np.int64).min) or larger than 18446744073709551615 (np.iinfo(np.uint64).max) are passed in, it is very likely they will be converted to float so that they can be stored in an ndarray. These warnings apply similarly to Series since it internally leverages ndarray.

  Parameters:
    arg scalar, list, tuple, 1-d array, Index, or Series

      Argument to be converted.

    errors{‘raise’, ‘coerce’}, default ‘raise’

      - If ‘raise’, then invalid parsing will raise an exception.

      - If ‘coerce’, then invalid parsing will be set as NaN.

    downcast str, default None

      Can be ‘integer’, ‘signed’, ‘unsigned’, or ‘float’. If not None, and if the data has been successfully cast to a numerical dtype (or if the data was numeric to begin with), downcast that resulting data to the smallest numerical dtype possible according to the following rules:

      - ‘integer’ or ‘signed’: smallest signed int dtype (min.: np.int8)

      - ‘unsigned’: smallest unsigned int dtype (min.: np.uint8)

      - ‘float’: smallest float dtype (min.: np.float32)

      As this behaviour is separate from the core conversion to numeric values, any errors raised during the downcasting will be surfaced regardless of the value of the ‘errors’ input.

      In addition, downcasting will only occur if the size of the resulting data’s dtype is strictly larger than the dtype it is to be cast to, so if none of the dtypes checked satisfy that specification, no downcasting will be performed on the data.

    dtype_backend{‘numpy_nullable’, ‘pyarrow’}

      Back-end data type applied to the result (still experimental). If not specified, the default behavior is to not use nullable data types. If specified, the behavior is as follows:

      - `"numpy_nullable"`: returns nullable-dtype-backed object

      - `"pyarrow"`: returns with pyarrow-backed nullable object

      Added in version 2.0.

  Returns:
    scalar, Series, or Index

      For numeric scalars the type is preserved, whereas other scalars return `int` if possible, otherwise `float`. For 1-d: `Series` if Series, `Index` if Index, otherwise an array as specified by `dtype_backend`.

      If `errors='coerce'`, un-parseable values become `NaN` (or `pd.NA` if `dtype_backend` is not the default). If `errors='raise'` (default), a `ValueError` is raised for invalid values.

  Raises:
    ValueError

      If the input contains non-numeric values and errors=’raise’.

    TypeError

      If the input is not list-like, 1D, or scalar convertible to numeric, such as nested lists or unsupported input types (e.g., dict).

  See also

  `DataFrame.astype`

    Cast argument to a specified dtype.

  `to_datetime`

    Convert argument to datetime.

  `to_timedelta`

    Convert argument to timedelta.

  `numpy.ndarray.astype`

    Cast a numpy array to a specified type.

  `DataFrame.convert_dtypes`

    Convert dtypes.

  Examples

  Take separate series and convert to numeric, coercing when told to

      >>> s = pd.Series(["1.0", "2", -3])
      >>> pd.to_numeric(s)
      0    1.0
      1    2.0
      2   -3.0
      dtype: float64
      >>> pd.to_numeric(s, downcast="float")
      0    1.0
      1    2.0
      2   -3.0
      dtype: float32
      >>> pd.to_numeric(s, downcast="signed")
      0    1
      1    2
      2   -3
      dtype: int8
      >>> s = pd.Series(["apple", "1.0", "2", -3])
      >>> pd.to_numeric(s, errors="coerce")
      0    NaN
      1    1.0
      2    2.0
      3   -3.0
      dtype: float64

  Downcasting of nullable integer and floating dtypes is supported:

      >>> s = pd.Series([1, 2, 3], dtype="Int64")
      >>> pd.to_numeric(s, downcast="integer")
      0    1
      1    2
      2    3
      dtype: Int8
      >>> s = pd.Series([1.0, 2.1, 3.0], dtype="Float64")
      >>> pd.to_numeric(s, downcast="float")
      0    1.0
      1    2.1
      2    3.0
      dtype: Float32

  Scalar input returns a scalar:

      >>> pd.to_numeric("42")
      np.int64(42)
      >>> pd.to_numeric("3.14")
      np.float64(3.14)

  Index input returns an Index:

      >>> pd.to_numeric(pd.Index(["1", "2", "3"]))
      Index([1, 2, 3], dtype='int64')