pandas-dev/pandas · error · NotImplementedError

replace is not supported with a re.Pattern, callable repl…

Error message

replace is not supported with a re.Pattern, callable repl, case=False, flags!=0, or when the replacement string contains named group references (\g<...>)

What it means

NotImplementedError raised in _str_replace of the ArrowStringArray mixin when the call uses features the pyarrow backend cannot express: a compiled re.Pattern as pat, a callable repl, case=False, non-zero flags, or a replacement string containing named group references (\g<...>). pandas surfaces this so users know to fall back rather than get silently wrong output.

Solutions

Cast to object dtype for that operation: s.astype(object).str.replace(re.compile(r'\d+'), 'x').
Replace case=False / flags with a regex pattern that embeds the case behavior (e.g. inline (?i)).
Avoid named-group references in repl; use numbered groups (\1, \2) which pyarrow supports.
Inline the callable repl as a non-regex transform applied via .map after replace.

Example fix

# before (pa_series is dtype str[pyarrow])
pa_series.str.replace(re.compile(r'\d+'), 'x')
# after
pa_series.astype(object).str.replace(re.compile(r'\d+'), 'x')

Defensive patterns

Strategy: fallback

Validate before calling

import re
def safe_str_replace(s, pat, repl, **kw):
    unsupported = (
        isinstance(pat, re.Pattern)
        or callable(repl)
        or not kw.get('case', True)
        or kw.get('flags', 0)
        or (isinstance(repl, str) and r'\g<' in repl)
    )
    if unsupported and 'pyarrow' in str(s.dtype):
        s = s.astype(object)
    return s.str.replace(pat, repl, **kw)

Type guard

def needs_object_for_replace(s, pat, repl, case=True, flags=0) -> bool:
    import re
    return 'pyarrow' in str(s.dtype) and (
        isinstance(pat, re.Pattern) or callable(repl)
        or not case or flags
        or (isinstance(repl, str) and r'\g<' in repl)
    )

Try / catch

try:
    s.str.replace(pat, repl, **kw)
except NotImplementedError as e:
    if 'replace is not supported' in str(e):
        s.astype(object).str.replace(pat, repl, **kw)
    else:
        raise

Prevention

On pyarrow-backed strings, prefer plain string patterns with no flags and numbered group references.
Cast to object dtype for the rare replace that needs re.Pattern / callable repl / flags.

When it happens

Trigger: On a pyarrow-backed string Series: s.str.replace(re.compile(r'\d+'), 'x'); s.str.replace('a', lambda m: m.group(0).upper()); s.str.replace('a','b', flags=re.I); s.str.replace('a','\g<name>').

Common situations: Enabling the pyarrow string dtype globally (pd.options.future.infer_string or dtype=str[pyarrow]) and then using advanced regex replace patterns previously written for object strings.

Related errors

AI-assisted analysis of pandas-dev/pandas@3b7651241d (2026-08-11). Data as JSON: /api/errors/319db337ada2d300. Report an issue: GitHub.

Appendix: source

Thrown at pandas/core/arrays/_arrow_string_mixins.py:262

        )

    def _str_replace(
        self,
        pat: str | re.Pattern,
        repl: str | Callable,
        n: int = -1,
        case: bool = True,
        flags: int = 0,
        regex: bool = True,
    ) -> Self:
        if (
            isinstance(pat, re.Pattern)
            or callable(repl)
            or not case
            or flags
            or (isinstance(repl, str) and r"\g<" in repl)
        ):
            raise NotImplementedError(
                "replace is not supported with a re.Pattern, callable repl, "
                "case=False, flags!=0, or when the replacement string contains "
                "named group references (\\g<...>)"
            )

        if pat == "":
            # pyarrow hangs for empty patterns
            # (https://github.com/apache/arrow/issues/39149)
            # use same func definition as ObjectStringArrayMixin._str_replace
            if regex:
                count = n if n >= 0 else 0
                func = lambda val: re.sub(pat, repl, val, count=count)
            else:
                func = lambda val: val.replace(pat, repl, n)

            result = self._apply_elementwise(func)
            return self._from_pyarrow_array(
                pa.chunked_array(result, type=self._pa_array.type)

View on GitHub (pinned to 3b7651241d)