python-telegram-bot/python-telegram-bot · warning · PTBDeprecationWarning

Positional passing of `filename` or keyword usage of `filena

Error message

Positional passing of `filename` or keyword usage of `filename_depr` is deprecated. `filename` will become a keyword-only argument.

What it means

InputMediaAnimation.__init__ emits a PTBDeprecationWarning (since v22.8) when filename is passed via the deprecated filename_depr keyword or positionally. filename is becoming keyword-only; the warning tells you to update the call.

Source

Thrown at src/telegram/_files/inputmedia.py:510

        parse_mode: ODVInput[str] = DEFAULT_NONE,
        width: int | None = None,
        height: int | None = None,
        duration: TimePeriod | None = None,
        caption_entities: Sequence[MessageEntity] | None = None,
        # tag: deprecated 22.8
        filename_depr: str | None = None,
        # -
        has_spoiler: bool | None = None,
        thumbnail: "FileInput | None" = None,
        show_caption_above_media: bool | None = None,
        *,
        filename: str | None = None,
        api_kwargs: JSONDict | None = None,
    ):
        if filename_depr is not None and filename is not None:
            raise ValueError("`filename_depr` and `filename` are mutually exclusive.")
        if filename_depr is not None:
            warn(
                PTBDeprecationWarning(
                    "22.8",
                    "Positional passing of `filename` or keyword usage of `filename_depr`"
                    " is deprecated. `filename` will become a keyword-only argument.",
                ),
                stacklevel=2,
            )

        if isinstance(media, Animation):
            width = media.width if width is None else width
            height = media.height if height is None else height
            duration = duration if duration is not None else media._duration
            media = media.file_id
        else:
            # We use local_mode=True because we don't have access to the actual setting and want
            # things to work in local mode.
            effective_filename = filename_depr or filename
            media = parse_file_input(

View on GitHub (pinned to d3b69d2e9f)

Solutions

1. Replace filename_depr='x' with keyword filename='x'
2. Pass filename only as a keyword argument, never positionally
3. Run tests with warnings visible to catch remaining usages

Example fix

# before
media = InputMediaAnimation(fileobj, 'anim.gif')
# or InputMediaAnimation(fileobj, filename_depr='anim.gif')
# after
media = InputMediaAnimation(fileobj, filename='anim.gif')

assert 'filename_depr' not in kwargs and len([a for a in args if isinstance(a, str)]) == 0

When it happens

Trigger: Constructing InputMediaAnimation(..., filename_depr='a.gif') or passing filename as a positional argument.

Common situations: Old tutorials or codebases written against PTB < 22.8 where filename was accepted differently; CI runs with -W error turning warnings into failures.

Related errors

• successful_payment will no longer be considered an attachmen
• callback_data_json is not in the required format
• Unable to deserialize conversations_json. Not valid JSON
• `rate_limit_args` can only be used if a `ExtBot.rate_limiter
• The `pattern` must not be a coroutine function! Use an ordin

AI-assisted analysis of python-telegram-bot/python-telegram-bot@d3b69d2e9f (2026-08-28). Data as JSON: /api/errors/3b92ee0d95231c61. Report an issue: GitHub.