Guide · Open source

How to use Typer: build Python CLIs from type hints

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Typer is a Python library for building command-line interface (CLI) programs. You write normal Python functions with type hints, and Typer turns their parameters into command-line arguments and options, with automatic help text and shell completion. This guide shows you how to install it, write a first command, add subcommands and run an existing script as a CLI.

Typerfastapi/typer · ★ 20.2k · MIT Install options & downloads

Quick start

1Install uv. Install uv using the official uv installation guide linked from the Typer README.
2Add Typer. In your project folder, run uv add typer to install the library and the typer command.
3Write a function. Create main.py with a function whose parameters have type hints, such as name: str.
4Run it with typer. Run typer main.py run to execute the function as a CLI, or add --help to see generated usage.
5Switch to typer.run. Import typer and call typer.run(main) inside the __name__ check to run the script directly with Python.
6Add subcommands. Create typer.Typer(), decorate functions with @app.command(), and finish with app().

Install Typer with uv

Install uv first, then add Typer to your project. The README's recommended command is shown below. Adding Typer this way installs both the Typer library and the typer command into the project's virtual environment.

If you prefer pip, install typer inside a virtual environment instead. The project's installation guide describes the alternative steps.

uv add typer

Run a plain function with the typer command

You can use the typer command to run a Python script as a CLI without changing the script. Create main.py with a function that takes a name parameter. The script does not even need to import Typer.

Run it with typer main.py run. Without an argument you get an error saying name is missing. Adding --help shows usage generated automatically, and passing a value such as Camila runs the function.

Missing required arguments produce an error message automatically.
Help text is generated for free with --help.
Auto-completion works when you use the typer command or create a Python package and run it with --install-completion.

$ typer main.py run
$ typer main.py run --help
$ typer main.py run Camila

Use Typer in your own code with typer.run

To use Typer inside your script, import it and call typer.run(main) under the standard __name__ check. The function's parameters become command-line arguments.

You can run the script with uv run python main.py. The same error and help behaviour appears, and passing Camila prints the greeting. The README also notes you can call the script with the typer command, but you do not need to.

import typer


def main(name: str):
    print(f"Hello {name}")


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

Add subcommands with typer.Typer

When your tool needs more than one action, create a typer.Typer() app and register each function with @app.command(). Each decorated function becomes a subcommand. Call app() at the bottom of the script instead of typer.run.

In the example, hello and goodbye are two subcommands. The goodbye command has a boolean parameter called formal, which Typer exposes as --formal and --no-formal automatically.

Create the app with app = typer.Typer().
Decorate each function with @app.command().
Run the app with app() under the __name__ check.

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()

Check the help for each command

Run the script with --help to see the list of subcommands. Then run hello --help or goodbye --help to see the arguments and options for each one. Typer builds these help pages from your function signatures, so the help stays in sync with the code.

$ uv run python main.py --help
$ uv run python main.py hello --help
$ uv run python main.py goodbye --help

What people use it for

Build a small command-line tool that takes a file path and options from a Python script.
Turn an existing Python script into a CLI quickly using the typer command, without editing the script.
Create a multi-command tool with subcommands such as hello and goodbye, grouped under one app.
Add automatic help text and shell completion to a command-line tool without writing argument parsing code.

Frequently asked questions

Is Typer free to use?

Typer is released under the MIT licence, as listed in the project details. The MIT licence is a permissive open-source licence; read the licence file in the repository for the full terms.

What do I need to install Typer?

Typer is a Python library, so you need Python and a way to install packages. The README recommends uv, with pip inside a virtual environment as an alternative. The README does not state a Python version explicitly, so check the installation guide before you start.

How do I install Typer?

Install uv, then run uv add typer in your project folder. This adds Typer and the typer command to the project's virtual environment. If you use pip, install it inside a virtual environment.

Can Typer run a Python script that does not use Typer?

Yes. The typer command can run a script such as main.py that contains only a normal function, converting it into a CLI application without changes to the file.

Does Typer support subcommands?

Yes. Create a typer.Typer() app and add functions with @app.command(). The README describes creating arbitrarily complex trees of commands and groups of subcommands.

Is Typer a good alternative to argparse or Click?

Typer is a good fit when you want to define arguments with Python type hints and get less boilerplate. The project lists Click, argparse, docopt and Fire as comparable projects. Pick the one whose style and features match your tool.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Typer suits Python developers who already use type hints and want to write small or medium command-line tools with little boilerplate, including subcommands. It is not a fit for non-Python projects, graphical interfaces, or beginners who have not yet learned Python functions and type hints. If you need a GUI, choose a different kind of toolkit.

Install options & downloads