Prepare values for NumPy-based computation
A numerical algorithm accepts ndarray input rather than a labeled DataFrame.
Pandas · Module
df.to_numpy
DataFrame.to_numpy converts a DataFrame’s values into a NumPy array without its index or column labels. It chooses a common dtype by default, while dtype, copy, and na_value provide explicit control.
How it works
Call this method on a DataFrame to obtain its values as a NumPy array without the index or column labels. Pandas chooses one common NumPy dtype unless you provide dtype; mixed or incompatible column types can require coercion, copying, or an object array.
Syntax
DataFrame.to_numpy(dtype=None, copy=False, na_value=<no_default>)Parameters
| Name | Type | Description |
|---|---|---|
dtype | str or numpy.dtype, optional | Dtype passed to numpy.asarray(); defaults to pandas' selected common dtype. |
copy | bool, default False | Whether to ensure the returned array is not a view on another array; defaults to False. |
na_value | Any, optional | Value used for missing values; its default depends on dtype and column dtypes. |
Returns
numpy.ndarray — the NumPy array representing the DataFrame values.
Key points
- Use the method to obtain the frame's values in NumPy-array form.
- Without dtype, pandas chooses one common NumPy dtype across the columns.
- Pass a string or NumPy dtype to request the output representation.
- copy=True requests an independent result rather than a view.
- na_value lets you choose the representation used for missing entries.
- The return value is a numpy.ndarray containing the DataFrame's values.
Common mistakes
- Conversion can allocate memory and coerce values, so it may be costly for large or heterogeneous frames.
- The default does not promise that the returned array shares memory with the DataFrame.
- Combining numeric and non-numeric columns can produce an object-dtype array.
Example: Convert a DataFrame to a NumPy array
import pandas as pd
frame = pd.DataFrame({"a": [1, 2], "b": [3.0, 4.5]})
array = frame.to_numpy(dtype="float32", copy=True)
print(array)
print(array.dtype)This converts the frame's values to a NumPy array with an explicitly selected dtype and a requested copy.
When to use it
Normalize the array dtype
A downstream API requires a specific array dtype.
Choose missing-value representation
Missing entries need a sentinel value in an exported array.
Interview questions
QWhat does DataFrame.to_numpy return?
It returns a NumPy array containing the DataFrame values. Row and column labels are not included, and the result normally uses a common NumPy dtype for all columns.
Follow-up: What happens with mixed numeric types? Pandas selects a common type capable of representing them, such as float32 for float16 and float32 input.
QHow does dtype affect the result?
dtype controls the dtype passed to numpy.asarray(). If it is omitted, pandas derives a common NumPy dtype from the DataFrame's column dtypes.
Follow-up: Why can dtype selection matter? Choosing a suitable dtype can avoid an unintended object array, while incompatible values may still require coercion.
QDoes copy=False guarantee shared memory?
copy defaults to False and avoids copying when possible, but it does not guarantee a view. Set copy=True when the returned array must not be a view on another array.
Follow-up: What additional control is available for missing values? The na_value argument specifies the value used to represent missing entries.
Related
DataFrame.valuesSeries.to_numpyIndex.to_numpyDataFrame.iloc