PaddlePaddle/PaddleOCR · warning · DeprecationWarning

The function 'replace_sub()' is deprecated, please use 'upgr

Error message

The function 'replace_sub()' is deprecated, please use 'upgrade_sublayer()' instead.

What it means

rec_pphgnetv2 defines replace_sub() as a hard-removed deprecated API: calling it always raises DeprecationWarning with instructions to use upgrade_sublayer(). upgrade_sublayer(self, layer_name_pattern, handle_func) applies handle_func(layer, pattern) to each matching sublayer and returns the modified layers — it is the drop-in replacement. Note Python only treats DeprecationWarning specially when raised as a warning via warnings.warn; here it is raised as an exception, so it always aborts.

Source

Thrown at ppocr/modeling/backbones/rec_pphgnetv2.py:562

            return_patterns = stages_pattern
        # return_stages is int or bool
        if type(return_stages) is int:
            return_stages = [return_stages]
        if isinstance(return_stages, list):
            if max(return_stages) > len(stages_pattern) or min(return_stages) < 0:
                return_stages = [
                    val
                    for val in return_stages
                    if val >= 0 and val < len(stages_pattern)
                ]
            return_patterns = [stages_pattern[i] for i in return_stages]

        if return_patterns:
            self.update_res(return_patterns)

    def replace_sub(self, *args, **kwargs) -> None:
        msg = "The function 'replace_sub()' is deprecated, please use 'upgrade_sublayer()' instead."
        raise DeprecationWarning(msg)

    def upgrade_sublayer(
        self,
        layer_name_pattern: Union[str, List[str]],
        handle_func: Callable[[nn.Layer, str], nn.Layer],
    ) -> Dict[str, nn.Layer]:
        """use 'handle_func' to modify the sub-layer(s) specified by 'layer_name_pattern'.

        Args:
            layer_name_pattern (Union[str, List[str]]): The name of layer to be modified by 'handle_func'.
            handle_func (Callable[[nn.Layer, str], nn.Layer]): The function to modify target layer specified by 'layer_name_pattern'. The formal params are the layer(nn.Layer) and pattern(str) that is (a member of) layer_name_pattern (when layer_name_pattern is List type). And the return is the layer processed.

        Returns:
            Dict[str, nn.Layer]: The key is the pattern and corresponding value is the result returned by 'handle_func()'.

        Examples:

            from paddle import nn

View on GitHub (pinned to 2661c7c0ef)

Solutions

Replace the call: backbone.upgrade_sublayer(layer_name_pattern, handle_func) — same semantics, returns Dict[str, nn.Layer]
Update any helper utilities that branch on hasattr(model, 'replace_sub') to also prefer upgrade_sublayer

Example fix

# before
model.backbone.replace_sub(r'.*conv', lambda layer, name: replace_with_fp16(layer))

# after
model.backbone.upgrade_sublayer(r'.*conv', lambda layer, name: replace_with_fp16(layer))

Defensive patterns

Strategy: fallback

Validate before calling

replace = getattr(backbone, 'upgrade_sublayer', None) or getattr(backbone, 'replace_sub', None)
assert replace is not None, 'no sublayer-replacement API available'
replace(pattern, handle_func)

Type guard

def sublayer_api(backbone):
    return getattr(backbone, 'upgrade_sublayer', None) or getattr(backbone, 'replace_sub', None)

Try / catch

try:
    backbone.replace_sub(pattern, fn)
except DeprecationWarning:
    backbone.upgrade_sublayer(pattern, fn)

Prevention

Target upgrade_sublayer directly; it exists on current PPHGNetV2
Pin your PaddleOCR version in lockfiles so API removals don't surprise scripts
Centralize layer-rewriting helpers in one module so migrations touch one place

When it happens

Trigger: Calling backbone.replace_sub('conv', fn) or replace_sub(segments, fn) on a PPHGNetV2 backbone instance; typical when porting FP16/reparam hooks or channel-pruning scripts written against older PaddleOCR/PaddleX layer APIs.

Common situations: Upgrading PaddleOCR and re-running an old quantization/pruning script that used replace_sub; code copied from another backbone class where replace_sub still exists as a working Paddle API.

Related errors

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/3fb11491d55361ae. Report an issue: GitHub.