NumPy interoperability
Pass a table's raw values to NumPy-based code that does not need pandas labels.
Pandas · Pipe
df.values
DataFrame.values exposes a DataFrame's cell data as a NumPy array without index or column labels. Prefer DataFrame.to_numpy() for new code.
How it works
Accessing DataFrame.values produces a NumPy array containing the DataFrame's cell values and removes both axes labels. Prefer DataFrame.to_numpy() when you need explicit control over dtype, copying, or missing-value representation.
Syntax
DataFrame.valuesReturns
numpy.ndarray — the values of the DataFrame.
Key points
- The property converts the DataFrame's tabular data into a NumPy array.
- The output contains cell values but excludes both the index and column labels.
- The return value is a
numpy.ndarraycontaining the DataFrame data. - When columns have different dtypes, pandas chooses a common dtype capable of representing all values.
- A numeric example of implicit promotion is a frame mixing
float16andfloat32, which yieldsfloat32output.
Common mistakes
- This property is retained for compatibility, but the documentation recommends
DataFrame.to_numpy()for new code. - Mixed column dtypes can cause the returned array to be implicitly upcast to a common dtype, potentially changing how values are represented.
- The result does not preserve index or column labels, so use labeled pandas operations when those labels matter.
Example: Extract unlabeled values
import pandas as pd
frame = pd.DataFrame({"age": [3, 29], "height": [94, 170]})
values = frame.values
print(values)
print(values.shape)The property returns the data as a NumPy array, without the DataFrame's index or column labels.
When to use it
Quick data inspection
Inspect the rectangular data representation during debugging or exploratory analysis.
Array-oriented processing
Obtain a compact two-dimensional array for homogeneous tabular data.
Interview questions
QWhat does DataFrame.values return?
DataFrame.values is a property that returns a NumPy representation of the DataFrame. It contains the cell values only; the index and column labels are omitted.
Follow-up: What happens with mixed column dtypes? The result uses a common accommodating dtype, so values may be implicitly upcast; for example, compatible numeric types can produce a broader numeric dtype.
QHow are labels and dtypes handled?
The returned array has rows and columns corresponding to the DataFrame's rows and columns, but it has no pandas axis labels. Its dtype is determined by the values across the columns rather than necessarily preserving each column's dtype.
Follow-up: Why can a mixed-type frame yield an object array? A single NumPy array needs one dtype, so heterogeneous values may require the broadest type that can represent them.
QWhat should new code use instead of DataFrame.values?
The documentation recommends DataFrame.to_numpy() instead of .values. to_numpy() is the explicit API for converting to a NumPy array and is the preferred modern alternative.
Follow-up: When should a developer avoid conversion entirely? When labels or pandas semantics are needed, keep the DataFrame and use pandas indexing or transformation methods instead.
Related
DataFrame.to_numpyDataFrame.indexDataFrame.columns