Skip to main content
`Ctrl`+`K`

# pandas.DataFrame.values

property DataFrame.values

  Return a Numpy representation of the DataFrame.

  Warning

  We recommend using `DataFrame.to_numpy()` instead. `.values` offers no way to control the output `dtype`, copy semantics, or the value used to fill missing entries, while `DataFrame.to_numpy()` exposes those as the `dtype`, `copy`, and `na_value` arguments. The mutability of the result also depends on the DataFrame’s internal block layout: when the DataFrame is backed by a single block the result is a read-only view (writes raise); when there are multiple blocks the result is a writable copy whose mutations do not propagate back to the DataFrame.

  Only the values in the DataFrame will be returned, the axes labels will be removed.

  Returns:
    numpy.ndarray

      The values of the DataFrame.

  See also

  `DataFrame.to_numpy`

    Recommended alternative to this method.

  `DataFrame.index`

    Retrieve the index labels.

  `DataFrame.columns`

    Retrieving the column names.

  Notes

  The returned array is not intended to be written to. When the DataFrame is backed by a single NumPy array (single dtype, single block), the result is a read-only view; when the DataFrame has multiple internal blocks (e.g. after adding a new column), the result is a copy and modifications to it will not be reflected in the original DataFrame. Use `DataFrame.to_numpy()` for more explicit control over copy behavior, or use `DataFrame.iloc` to modify values in-place.

  The dtype will be a lower-common-denominator dtype (implicit upcasting); that is to say if the dtypes (even of numeric types) are mixed, the one that accommodates all will be chosen. Use this with care if you are not dealing with the blocks.

  e.g. If the dtypes are float16 and float32, dtype will be upcast to float32. If dtypes are int32 and uint8, dtype will be upcast to int32. By `numpy.find_common_type()` convention, mixing int64 and uint64 will result in a float64 dtype.

  Examples

  A DataFrame where all columns are the same type (e.g., int64) results in an array of the same type.

      >>> df = pd.DataFrame(
      ...     {"age": [3, 29], "height": [94, 170], "weight": [31, 115]}
      ... )
      >>> df
         age  height  weight
      0    3      94      31
      1   29     170     115
      >>> df.dtypes
      age       int64
      height    int64
      weight    int64
      dtype: object
      >>> df.values
      array([[  3,  94,  31],
             [ 29, 170, 115]])

  A DataFrame with mixed type columns(e.g., str/object, int64, float32) results in an ndarray of the broadest type that accommodates these mixed types (e.g., object).

      >>> df2 = pd.DataFrame(
      ...     [
      ...         ("parrot", 24.0, "second"),
      ...         ("lion", 80.5, 1),
      ...         ("monkey", np.nan, None),
      ...     ],
      ...     columns=("name", "max_speed", "rank"),
      ... )
      >>> df2.dtypes
      name             str
      max_speed    float64
      rank          object
      dtype: object
      >>> df2.values
      array([['parrot', 24.0, 'second'],
             ['lion', 80.5, 1],
             ['monkey', nan, None]], dtype=object)

  `DataFrame.to_numpy` produces the same array by default, but lets you choose how missing values are represented and request a guaranteed copy:

      >>> df3 = pd.DataFrame({"a": [1, 2], "b": [3.0, np.nan]})
      >>> df3.values
      array([[ 1.,  3.],
             [ 2., nan]])
      >>> df3.to_numpy(na_value=-1)
      array([[ 1.,  3.],
             [ 2., -1.]])
      >>> df3.to_numpy(dtype="float32", copy=True)
      array([[ 1.,  3.],
             [ 2., nan]], dtype=float32)