Skip to main content

Getting Started

Typer is a library for building CLI applications based on Python type hints. It is designed to be intuitive to write, easy to use for end-users, and highly scalable from simple scripts to complex CLI tools.

Prerequisites​

  • Python: Version 3.10 or higher is required.
  • Dependencies: Typer automatically installs click, rich, and shellingham.

Installation​

You can install Typer using pip or uv.

Using pip​

pip install typer

Using uv​

uv add typer

Hello World / Quick Start​

There are two main ways to use Typer: using the typer.run() shortcut for simple scripts, or creating a typer.Typer() instance for more complex applications with subcommands.

Simple Script (typer.run)​

Create a file named main.py:

import typer

def main(name: str, lastname: str = "", formal: bool = False):
    """
    Say hello to NAME, optionally with a LASTNAME.
    """
    if formal:
        print(f"Greetings {name} {lastname}")
    else:
        print(f"Hello {name} {lastname}")

if __name__ == "__main__":
    typer.run(main)

Run it directly with Python:

python main.py Camila
# Output: Hello Camila 

python main.py --formal Camila --lastname "Ramírez"
# Output: Greetings Camila Ramírez

Multiple Commands (typer.Typer)​

For applications with subcommands, use the Typer class:

import typer

app = typer.Typer()

@app.command()
def hello(name: str):
    print(f"Hello {name}")

@app.command()
def goodbye(name: str, formal: bool = False):
    if formal:
        print(f"Goodbye Ms. {name}. Have a good day.")
    else:
        print(f"Bye {name}!")

if __name__ == "__main__":
    app()

Run the subcommands:

python main.py hello Camila
# Output: Hello Camila

python main.py goodbye --formal Camila
# Output: Goodbye Ms. Camila. Have a good day.

Configuration​

Typer supports several environment variables to customize its behavior:

  • TYPER_USE_RICH: Set to 0 or False to disable Rich Help Formatting Overview-formatted output (colors and formatting in errors/help).
  • TERMINAL_WIDTH: Overrides the detected terminal width for help text wrapping.
  • TYPER_STANDARD_TRACEBACK: If set, Typer will show standard Python tracebacks instead of simplified ones.

Verify Installation​

Confirm that the Typer CLI tool is installed and working:

typer --help

You can also use the typer command to run scripts that don't even import Typer:

# If main.py has a function main(name: str)
typer main.py run Camila

Next Steps​

  • CLI Arguments: Learn how to define required and optional CLI Arguments.
  • CLI Options: Customize flags and parameters using CLI Options.
  • Subcommands: Organize your CLI into Organizing Subcommands and Groups.
  • Validation: Add custom validation to your parameters.
  • Prompting: Use typer.prompt() and typer.confirm() for interactive input.

Troubleshooting​

Shell Completion Not Working​

If auto-completion isn't working in your terminal, try installing it explicitly for your shell:

python main.py --install-completion

Then restart your terminal or source your shell configuration file.

Rich Output Issues​

If you see strange characters in your terminal, it might not support Rich formatting. Disable it by setting:

export TYPER_USE_RICH=0