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

In a future major version attribute `{attribute}` will be of

Error message

In a future major version attribute `{attribute}` will be of type `datetime.timedelta`. You can opt-in early by setting `PTB_TIMEDELTA=true` or ``PTB_TIMEDELTA=1`` as an environment variable.

What it means

PTB 22.2+ warns that duration-like attributes (audio.duration, message.live_period, etc.) will change from float/int seconds to datetime.timedelta in a future major version. The warning fires on every read of such an attribute unless you opt in early.

Source

Thrown at src/telegram/_utils/datetime.py:276

    Note:
        When `PTB_TIMEDELTA` is not enabled, the function will issue a deprecation warning.

    Args:
        value (:obj:`datetime.timedelta`): The timedelta value to process.
        attribute (:obj:`str`): The name of the attribute at the caller scope, used for
            warning messages.

    Returns:
        - :obj:`None` if :paramref:`value` is None.
        - :obj:`datetime.timedelta` if `PTB_TIMEDELTA=true` or ``PTB_TIMEDELTA=1``.
        - :obj:`int` if the total seconds is a whole number.
        - float: otherwise.
    """
    if value is None:
        return None
    if os.getenv("PTB_TIMEDELTA", "false").lower().strip() in ["true", "1"]:
        return value
    warn(
        PTBDeprecationWarning(
            "v22.2",
            f"In a future major version attribute `{attribute}` will be of type"
            " `datetime.timedelta`. You can opt-in early by setting `PTB_TIMEDELTA=true`"
            " or ``PTB_TIMEDELTA=1`` as an environment variable.",
        ),
        stacklevel=2,
    )
    return (
        int(seconds)  # type: ignore[return-value]
        if (seconds := value.total_seconds()).is_integer()
        else seconds
    )

View on GitHub (pinned to d3b69d2e9f)

Solutions

1. Set environment variable PTB_TIMEDELTA=true (or 1) and migrate code to use datetime.timedelta
2. Pin python-telegram-bot to <22.2 until you can migrate
3. Suppress PTBDeprecationWarning via warnings filter as a temporary measure

Example fix

# before
duration = message.audio.duration  # warns

# after
import os
os.environ["PTB_TIMEDELTA"] = "true"
duration = message.audio.duration  # datetime.timedelta
print(duration.total_seconds())

import os
os.environ.setdefault("PTB_TIMEDELTA", "true")  # set before importing telegram

When it happens

Trigger: Reading attributes like Message.duration, live_period, start_timestamp, audio.duration, gif_duration, mpeg4_duration via to_timedelta_value-based properties while PTB_TIMEDELTA env var is not set to true/1.

Common situations: Upgrading to python-telegram-bot >= 22.2 without setting PTB_TIMEDELTA; libraries or user code reading duration attributes trigger the deprecation warning repeatedly.

Related errors

• `filename_depr` and `filename` are mutually exclusive.
• You passed different entities as '{deprecated_arg_name}' and
• Generator-based coroutines are deprecated in create_task and
• Support for pytz timezones is deprecated and will be removed
• The `ConversationHandler` only handles updates of type `tele

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