BUG: typer.Option parameters treated as boolean flags with Click >= 8.3.0

[cconroy]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the Typer documentation, with the integrated search.
• I already searched in Google "How to X in Typer" and didn't find any information.
• I already read and followed all the tutorials in the docs and didn't find an answer.
• I already checked if it is not related to Typer but to Click.

Commit to Help

• I commit to help with one of those options 👆

Example Code

import typer
from typing import Annotated

app = typer.Typer()

@app.command()
def run(name: Annotated[str, typer.Option("--name")]):
    print(f"name={name!r}")

if __name__ == "__main__":
    app()

Description

Restating the example code above:

repro.py:

import typer
from typing import Annotated

app = typer.Typer()

@app.command()
def run(name: Annotated[str, typer.Option("--name")]):
    print(f"name={name!r}")

pip install "typer[all]==0.12.0" "click==8.3.2"
python repro.py --name hello

Expected:

name='hello'

Actual:

Error: Got unexpected extra argument (hello)

To confirm the option is being registered as a flag, introspect it:

repro-inspect.py

import typer
from typing import Annotated

app = typer.Typer()

@app.command()
def run(name: Annotated[str, typer.Option("--name")]):
    pass

cli = typer.main.get_command(app)
for param in cli.params:
    if param.name == "name":
        print(f"type={param.type}, is_flag={param.is_flag}")

python repro-inspect.py --name hello

Output with Click 8.3.x:

type=STRING, is_flag=True

type=STRING confirms Typer correctly identified the parameter type. is_flag=True
reveals that Click is overriding the interpretation based on flag_value.

Before Click 8.3.0, flag_value defaulted to None. Click's internal guard was
effectively if flag_value is not None, so Typer passing None was harmless — it
matched the default and is_flag was left unset.

Click 8.3.0 introduced an UNSET sentinel and changed the signature and guard:

# click/core.py ~line 2723
flag_value: t.Any = UNSET,

# ~line 2777
if is_flag is None:
    if flag_value is not UNSET:   # None is not UNSET → True for every Typer option
        is_flag = True

Because Typer always passes flag_value=None, Click 8.3.x now evaluates
None is not UNSET as True for every option, unconditionally setting is_flag=True
on all of them — regardless of the declared Python type.

Possible Fix

Perhaps typer should not forward flag_value to Click when it holds the None default (not set by user)

Operating System

macOS

Operating System Details

No response

Typer Version

0.12.0

Python Version

Python 3.13.0

Additional Context

No response

[cookesan]

This looks like the old Typer/Click compatibility edge rather than expected Option behavior. Typer has moved a long way since 0.12.0; the current package metadata requires Click >= 8.2.1, and the current code path no longer appears to pass the stale flag_value=None shape that Click 8.3 exposes here.

The first thing I would do is reproduce on current Typer. If you are stuck on Typer 0.12.0, pin Click below 8.3 for that environment. If upgrading is possible, upgrade Typer instead of working around it in every option declaration.

[svlandeg]

Great advice, we'd indeed need to verify whether this still happens on the latest Typer release.

[cconroy]

My apologies: I should have checked a newer version first! I was able to upgrade my project to 0.24.2 and can confirm this issue is no longer present. Thanks!