typer helloworld.main run raises ModuleNotFoundError, but py -m typer helloworld.main run works

[martyszewski]

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

from rich import print
from typer import Argument, Typer

app = Typer()


@app.command()
def hello(name: str = Argument(..., help="Name to greet")):
    print(f"Hello {name}!")


if __name__ == "__main__":
    app()

Description

Hi! I have a minimal setup:

helloworld-typer/
├── helloworld/
│   ├── __init__.py
│   └── main.py
└── .venv/

In main.py I define a simple Typer app: (see example code)
I activate the virtual environment and install typer. Then:

• py -m helloworld.main works
• typer helloworld.main run fails with ModuleNotFoundError: No module named 'helloworld'
• typer helloworld\main.py run works
• py -m typer helloworld.main run works

It seems the typer CLI is executed from .venv/Scripts, so the project root isn’t on sys.path.
Launching with python -m typer helloworld.main run or PYTHONPATH=. typer … fixes it.

Is this the intended behaviour? Would it make sense for the typer launcher to prepend the CWD to sys.path (mirroring python -m), or should the docs recommend using python -m typer during local development?

I’ve read the docs at https://typer.tiangolo.com/tutorial/typer-command/#run-a-package-or-module and expected typer helloworld.main run to work too.
Is this a misunderstanding on my side about how typer resolves modules, or is there an import context difference between typer and python -m?

Thanks in advance for clarifying!

Operating System

Windows

Operating System Details

Guest OS: Windows 11 — clean installation, no third-party tweaks

• Edition: Windows 11 Pro
• Version: 24H2
• Installed on: 7/‎12/‎2025
• OS build: 26100.4652
• Experience: Windows Feature Experience Pack 1000.26100.128.0

Python: CPython 3.13.5 (64-bit) — installed from the official python.org installer, added to PATH
Extra tooling: pip 25.x (bundled), Typer 0.16.x, Rich 14.x — installed in an isolated virtual-env (python -m venv .venv)

Typer Version

0.16.0

Python Version

3.13.5

Additional Context

No response