In pandas 3.0, how do Series.values, Series.array and Series.to_numpy() differ on a text, Int64 or category column, and which should library code use?
answer
- reference versus conversion
- ExtensionArray versus ndarray
- the legacy attribute in between
- text is no longer object
- shared arrays cannot be written
basics
~20 sSeries.array returns the backing ExtensionArray without converting; to_numpy() always returns a NumPy ndarray, converting or copying when needed. .values is legacy: an ndarray for NumPy dtypes, the ExtensionArray otherwise, so in pandas 3.0 text columns give an ArrowStringArray.
solid answer
~40 s`.array` is a **reference**: it always returns a pandas `ExtensionArray`, the real one for extension dtypes (`IntegerArray` for `Int64`, `Categorical` for `category`, `ArrowStringArray` for text when PyArrow is installed) and a thin `NumpyExtensionArray` wrapper for NumPy dtypes. `to_numpy()` is a **conversion**: it always returns an `np.ndarray`, so a category column loses its categories and becomes an `object` array of values, and `Int64` with missing values becomes `float64` with `NaN`. `.values` sits in between: an ndarray for NumPy dtypes, the ExtensionArray for extension dtypes, and a UTC `datetime64` array for time-zone-aware data. In pandas 3.0 text infers the `str` dtype, so `.values` on a text column is no longer an `object` ndarray, and ndarray-only calls such as `.reshape` break. Library code should say what it needs: `.array` or `to_numpy(dtype=...)`.
code
python · 18 linesimport pandas as pd
name = pd.Series(["Oslo", "Lima"])
age = pd.Series([31, None], dtype="Int64")
kind = pd.Series(["a", "b", "a"], dtype="category")
for s in (name, age, kind):
print(s.dtype, type(s.array).__name__, type(s.values).__name__, s.to_numpy().dtype)
when = pd.Series(pd.date_range("2026-03-01", periods=2, tz="Europe/Oslo"))
print(type(when.array).__name__, when.values.dtype, when.to_numpy().dtype)
prices = pd.Series([9.5, 12.0])
arr = prices.to_numpy()
print(arr.flags.writeable)
try:
arr[0] = 0.0
except ValueError as err:
print("ValueError:", err)go deeper
Remember the rule of thumb: .array is the data as pandas stores it, to_numpy() is always a NumPy array, and .values is the old attribute to avoid.
Walk through the table: what each accessor returns for float64, Int64, category, str and tz-aware columns, and where conversion or copying happens.
Explain what a pandas 3.0 upgrade breaks: .values on text now returning an ExtensionArray, read-only arrays, and silent UTC conversion on tz-aware .values.
The decision is a codebase convention: ban .values in new code and require to_numpy with an explicit dtype at library boundaries, accepting the churn of migrating old helpers.
## Three ways to reach a Series' data A pandas **Series** stores its values in an array. For NumPy dtypes (`int64`, `float64`, `datetime64`) that array is a NumPy `ndarray`; for **extension dtypes** (`Int64`, `boolean`, `category`, `str`, time-zone-aware datetimes, Arrow-backed dtypes) it is a pandas **ExtensionArray**, an array type pandas defines itself. Three accessors expose it, and they make different promises: - **`Series.array`**: always an `ExtensionArray`, with **no conversion**. For extension dtypes it is the actual backing array; for NumPy dtypes it is a `NumpyExtensionArray` that wraps the ndarray without copying. - **`Series.to_numpy()`**: always a **NumPy `ndarray`**, converting and copying as needed. It takes `dtype=`, `na_value=` and `copy=`. - **`Series.values`**: the original attribute, which returns "ndarray or ndarray-like depending on the dtype". The pandas docs recommend `.array` or `to_numpy()` instead. | Column dtype | `.array` | `.values` | `.to_numpy()` | |---|---|---|---| | `float64` | `NumpyExtensionArray` | `ndarray` | `ndarray` (`float64`) | | `Int64` with missing values | `IntegerArray` | `IntegerArray` | `ndarray` (`float64`, `NaN`) | | `category` of text | `Categorical` | `Categorical` | `ndarray` (`object`), categories lost | | `str` (pandas 3.0 text) | `ArrowStringArray` with PyArrow | same as `.array` | `ndarray` (`object`) | | `datetime64[..., tz]` | `DatetimeArray` | `ndarray` (`datetime64`, converted to UTC, zone dropped) | `ndarray` (`object` of `Timestamp`, zone kept) | ## What changed in pandas 3.0 Two pandas 3.0 changes make the choice matter more than it used to: 1. **Text infers the `str` dtype.** In pandas 2.x, `pd.Series(["Oslo", "Lima"])` had dtype `object` and `.values` returned an `object` ndarray. In pandas 3.0 the same Series has dtype `str`, an extension dtype backed by PyArrow when it is installed (otherwise by NumPy objects), so `.values` returns an ExtensionArray. Code such as `df["city"].values.reshape(-1, 1)` now fails, because `ArrowStringArray` does not support `reshape`. `df["city"].to_numpy()` still returns an `object` ndarray and works. 2. **Arrays that share data are read-only.** With Copy-on-Write as the only mode, `to_numpy()` and `.values` on a NumPy-backed Series return a read-only view; writing into it raises `ValueError: assignment destination is read-only`. Use `to_numpy(copy=True)` when you need to mutate the array. The full Copy-on-Write rules are covered with pandas Copy-on-Write. ## Which one to use - **Library code that needs a NumPy array** (a numeric routine, a model, a plotting call): `to_numpy()`, with `dtype=` and `na_value=` when the column may be nullable. The result type is guaranteed. - **Code that needs the data as pandas holds it** (no copy, dtype and missing-value mask intact): `.array`. A `Categorical` keeps its categories, an `IntegerArray` keeps `pd.NA`. - **`.values`**: only when reading old code. Its result type depends on the dtype, which is exactly what changed under it for text columns in pandas 3.0. ## Migrating `.values` in an old codebase A 2.x codebase usually has `.values` scattered through helpers. A pandas 3.0 upgrade is a good moment to remove it, in this order: 1. **Search for `.values` on columns that can hold text.** These are the ones whose result type changed. Replace them with `.to_numpy()` where an ndarray is needed, or `.array` where the code only reads values. 2. **Search for ndarray-only operations on the result**: `.reshape`, `.flags`, in-place assignment such as `arr[mask] = 0`, and `isinstance(x, np.ndarray)` checks. Each one needs `to_numpy()`, and the in-place writes also need `copy=True`. 3. **Leave functions that already convert alone.** NumPy functions such as `np.unique` or `np.asarray` accept an ExtensionArray and convert it, so they often keep working. 4. **Add `dtype=`** wherever the downstream code assumes a numeric type, so that a nullable column added later cannot slip an `object` array through. The point is not that `.values` is wrong today, but that its return type is decided by the column's dtype, so every dtype change upstream silently changes what the helper receives. ## Time-zone-aware datetimes This is the case where `.values` silently changes the data rather than only the container. For a Series of `Europe/Oslo` timestamps, `.values` returns a `datetime64` ndarray **converted to UTC with the zone dropped**, so midnight in Oslo reads as 23:00 the previous day. `to_numpy()` returns an `object` array of `Timestamp` objects that keep the zone, and `.array` returns the `DatetimeArray` itself. If the downstream code compares wall-clock times, the `.values` result is wrong without raising anything. ## DataFrames A DataFrame has no `.array`; it has `to_numpy()` and `.values`, which both return a single 2-D ndarray with a common dtype. The per-column distinctions above apply when you pull one column out with `df["col"]`.
- A 2.x helper calls np.unique(df['city'].values); does it still work in pandas 3.0?`np.unique` converts its input with `np.asarray`, which turns the `ArrowStringArray` into an `object` ndarray, so it usually still runs. What breaks are ndarray methods called directly on the result, such as `.reshape` or `.flags`, and `isinstance(x, np.ndarray)` checks. Replacing `.values` with `.to_numpy()` restores the ndarray guarantee.
- How do you get a writable NumPy array from a float64 Series in pandas 3.0?Call `s.to_numpy(copy=True)`, or `np.array(s)`, which copies. The default `to_numpy()` returns a read-only view of the Series' data, so that writing into it cannot change the Series behind Copy-on-Write's back.
- .values always returns a NumPy ndarray
- Series.array copies the data into a new NumPy array
- to_numpy() on a category column keeps the categories
- In pandas 3.0 a text column's .values is still an object ndarray
- .values on tz-aware data keeps the local wall-clock times
Assumes pandas 3.0: text columns infer the str dtype, so .values returns an ExtensionArray where 2.x returned an object ndarray, and arrays that share a Series' data are read-only.