Prevent pandas 2.2.3 Series subclass name loss: add '_name' to _metadata to preserve the Series name on list indexing

Learn why pandas 2.2.3 Series subclasses lose the name on list indexing with _metadata and how to fix it: include '_name' in _metadata to keep labels consistent.

Subclassing pandas.Series is a common way to carry domain-specific behavior and attributes through data transformations. In pandas 2.2.3, there is a subtle pitfall: when you add custom metadata to a Series subclass, the series name may silently disappear during certain types of indexing. Here’s what happens, why it happens, and how to keep the name intact.

Reproducing the issue

The behavior differs depending on whether _metadata is defined. First, consider a subclass without any custom metadata. The name survives both slicing and list-based indexing.

import pandas as pd


class UserSeries(pd.Series):

    @property
    def _constructor(self):
        return UserSeries


arr = UserSeries([*'abc'], name='data')

print(f'''No _metadata:
  {isinstance(arr[0:1], UserSeries) = }
  {isinstance(arr[[0, 1]], UserSeries) = }
  {arr[0:1].name = }  
  {arr[[0, 1]].name = }
''')

class UserSeries(pd.Series):

    _metadata = ['flag']

    @property
    def _constructor(self):
        return UserSeries


arr = UserSeries([*'abc'], name='data')
arr.flag = 'MyProperty'

print(f'''With _metadata:
  {isinstance(arr[0:1], UserSeries) = }
  {isinstance(arr[[0, 1]], UserSeries) = }
  {arr[0:1].name = }  
  {arr[[0, 1]].name = }
  {getattr(arr[0:1], 'flag', 'NA') = }  
  {getattr(arr[[0, 1]], 'flag', 'NA') = }  
''')

Expected output shows the problematic asymmetry. When _metadata is set, slicing preserves the name, but list-based indexing drops it.

No _metadata:
  isinstance(arr[0:1], UserSeries) = True
  isinstance(arr[[0, 1]], UserSeries) = True
  arr[0:1].name = 'data'  
  arr[[0, 1]].name = 'data'

With _metadata:
  isinstance(arr[0:1], UserSeries) = True
  isinstance(arr[[0, 1]], UserSeries) = True
  arr[0:1].name = 'data'  
  arr[[0, 1]].name = None         <<< Name is lost here
  getattr(arr[0:1], 'flag', 'NA') = 'MyProperty'  
  getattr(arr[[0, 1]], 'flag', 'NA') = 'MyProperty'  

What’s really going on

The name attribute on a Series is a descriptor that operates on an internal string attribute named '_name'. When you do not override _metadata, '_name' is included by default, which allows pandas to propagate the name through operations. The moment you override _metadata, you take control of what gets carried over, and '_name' stops being included implicitly. As a result, certain indexing routes—like selecting with a list—can drop the name.

The fix

Explicitly include '_name' in _metadata alongside your custom fields. This restores the default behavior of name propagation even when you provide your own metadata.

import pandas as pd


class UserSeries(pd.Series):

    _metadata = ['extra_flag', '_name']

    @property
    def _constructor(self):
        return UserSeries


arr = UserSeries([*'abc'], name='data')

print(f'{arr[0:1].name = }')
print(f'{arr[[0, 1]].name = }')

# Output:
# arr[0:1].name = 'data'
# arr[[0, 1]].name = 'data'

Why this detail matters

Name consistency is essential when code relies on labels for downstream operations, logging, or interoperability with other components. Losing the name only in specific indexing paths leads to brittle behavior that is hard to diagnose. Ensuring '_name' is part of the propagated metadata keeps behavior consistent between slicing and list-based indexing, which helps avoid subtle surprises in pipelines and tests.

Takeaways

When defining custom metadata on a pandas.Series subclass in pandas 2.2.3, include '_name' in _metadata to preserve the series name across indexing operations. This small addition keeps your extended Series predictable and your data flows easier to reason about.