{"id":14012548,"url":"https://github.com/fastapi/typer","last_synced_at":"2026-01-06T13:16:35.820Z","repository":{"id":37271391,"uuid":"229937405","full_name":"fastapi/typer","owner":"fastapi","description":"Typer, build great CLIs. Easy to code. Based on Python type hints.","archived":false,"fork":false,"pushed_at":"2025-05-02T10:51:49.000Z","size":1688,"stargazers_count":16950,"open_issues_count":179,"forks_count":725,"subscribers_count":80,"default_branch":"master","last_synced_at":"2025-05-05T15:18:05.373Z","etag":null,"topics":["cli","click","python","python3","shell","terminal","typehints","typer"],"latest_commit_sha":null,"homepage":"https://typer.tiangolo.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fastapi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["tiangolo"]}},"created_at":"2019-12-24T12:24:11.000Z","updated_at":"2025-05-05T15:11:52.000Z","dependencies_parsed_at":"2022-07-16T11:00:50.051Z","dependency_job_id":"27c823a2-4d86-4181-a3bf-e5b86cbfd24e","html_url":"https://github.com/fastapi/typer","commit_stats":{"total_commits":789,"total_committers":70,"mean_commits":"11.271428571428572","dds":0.5221799746514575,"last_synced_commit":"77481a24288e37b0ee43847008a36eb7451c45a0"},"previous_names":["fastapi/typer","tiangolo/typer"],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastapi%2Ftyper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastapi%2Ftyper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastapi%2Ftyper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastapi%2Ftyper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastapi","download_url":"https://codeload.github.com/fastapi/typer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253028759,"owners_count":21842969,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","click","python","python3","shell","terminal","typehints","typer"],"created_at":"2024-08-10T23:00:53.181Z","updated_at":"2026-01-06T13:16:35.807Z","avatar_url":"https://github.com/fastapi.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://typer.tiangolo.com\"\u003e\u003cimg src=\"https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg#only-light\" alt=\"Typer\"\u003e\u003c/a\u003e\n\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003cem\u003eTyper, build great CLIs. Easy to code. Based on Python type hints.\u003c/em\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/fastapi/typer/actions?query=workflow%3ATest+event%3Apush+branch%3Amaster\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://github.com/fastapi/typer/actions/workflows/test.yml/badge.svg?event=push\u0026branch=master\" alt=\"Test\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/fastapi/typer/actions?query=workflow%3APublish\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://github.com/fastapi/typer/workflows/Publish/badge.svg\" alt=\"Publish\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://coverage-badge.samuelcolvin.workers.dev/redirect/fastapi/typer\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://coverage-badge.samuelcolvin.workers.dev/fastapi/typer.svg\" alt=\"Coverage\"\u003e\n\u003ca href=\"https://pypi.org/project/typer\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/v/typer?color=%2334D058\u0026label=pypi%20package\" alt=\"Package version\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n**Documentation**: \u003ca href=\"https://typer.tiangolo.com\" target=\"_blank\"\u003ehttps://typer.tiangolo.com\u003c/a\u003e\n\n**Source Code**: \u003ca href=\"https://github.com/fastapi/typer\" target=\"_blank\"\u003ehttps://github.com/fastapi/typer\u003c/a\u003e\n\n---\n\nTyper is a library for building \u003cabbr title=\"command line interface, programs executed from a terminal\"\u003eCLI\u003c/abbr\u003e applications that users will **love using** and developers will **love creating**. Based on Python type hints.\n\nIt's also a command line tool to run scripts, automatically converting them to CLI applications.\n\nThe key features are:\n\n* **Intuitive to write**: Great editor support. \u003cabbr title=\"also known as auto-complete, autocompletion, IntelliSense\"\u003eCompletion\u003c/abbr\u003e everywhere. Less time debugging. Designed to be easy to use and learn. Less time reading docs.\n* **Easy to use**: It's easy to use for the final users. Automatic help, and automatic completion for all shells.\n* **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs.\n* **Start simple**: The simplest example adds only 2 lines of code to your app: **1 import, 1 function call**.\n* **Grow large**: Grow in complexity as much as you want, create arbitrarily complex trees of commands and groups of subcommands, with options and arguments.\n* **Run scripts**: Typer includes a `typer` command/program that you can use to run scripts, automatically converting them to CLIs, even if they don't use Typer internally.\n\n## FastAPI of CLIs\n\n**Typer** is \u003ca href=\"https://fastapi.tiangolo.com\" class=\"external-link\" target=\"_blank\"\u003eFastAPI\u003c/a\u003e's little sibling, it's the FastAPI of CLIs.\n\n## Installation\n\nCreate and activate a \u003ca href=\"https://typer.tiangolo.com/virtual-environments/\" class=\"external-link\" target=\"_blank\"\u003evirtual environment\u003c/a\u003e and then install **Typer**:\n\n\u003cdiv class=\"termy\"\u003e\n\n```console\n$ pip install typer\n---\u003e 100%\nSuccessfully installed typer rich shellingham\n```\n\n\u003c/div\u003e\n\n## Example\n\n### The absolute minimum\n\n* Create a file `main.py` with:\n\n```Python\ndef main(name: str):\n    print(f\"Hello {name}\")\n```\n\nThis script doesn't even use Typer internally. But you can use the `typer` command to run it as a CLI application.\n\n### Run it\n\nRun your application with the `typer` command:\n\n\u003cdiv class=\"termy\"\u003e\n\n```console\n// Run your application\n$ typer main.py run\n\n// You get a nice error, you are missing NAME\nUsage: typer [PATH_OR_MODULE] run [OPTIONS] NAME\nTry 'typer [PATH_OR_MODULE] run --help' for help.\n╭─ Error ───────────────────────────────────────────╮\n│ Missing argument 'NAME'.                          │\n╰───────────────────────────────────────────────────╯\n\n\n// You get a --help for free\n$ typer main.py run --help\n\nUsage: typer [PATH_OR_MODULE] run [OPTIONS] NAME\n\nRun the provided Typer app.\n\n╭─ Arguments ───────────────────────────────────────╮\n│ *    name      TEXT  [default: None] [required]   |\n╰───────────────────────────────────────────────────╯\n╭─ Options ─────────────────────────────────────────╮\n│ --help          Show this message and exit.       │\n╰───────────────────────────────────────────────────╯\n\n// Now pass the NAME argument\n$ typer main.py run Camila\n\nHello Camila\n\n// It works! 🎉\n```\n\n\u003c/div\u003e\n\nThis is the simplest use case, not even using Typer internally, but it can already be quite useful for simple scripts.\n\n**Note**: auto-completion works when you create a Python package and run it with `--install-completion` or when you use the `typer` command.\n\n## Use Typer in your code\n\nNow let's start using Typer in your own code, update `main.py` with:\n\n```Python\nimport typer\n\n\ndef main(name: str):\n    print(f\"Hello {name}\")\n\n\nif __name__ == \"__main__\":\n    typer.run(main)\n```\n\nNow you could run it with Python directly:\n\n\u003cdiv class=\"termy\"\u003e\n\n```console\n// Run your application\n$ python main.py\n\n// You get a nice error, you are missing NAME\nUsage: main.py [OPTIONS] NAME\nTry 'main.py --help' for help.\n╭─ Error ───────────────────────────────────────────╮\n│ Missing argument 'NAME'.                          │\n╰───────────────────────────────────────────────────╯\n\n\n// You get a --help for free\n$ python main.py --help\n\nUsage: main.py [OPTIONS] NAME\n\n╭─ Arguments ───────────────────────────────────────╮\n│ *    name      TEXT  [default: None] [required]   |\n╰───────────────────────────────────────────────────╯\n╭─ Options ─────────────────────────────────────────╮\n│ --help          Show this message and exit.       │\n╰───────────────────────────────────────────────────╯\n\n// Now pass the NAME argument\n$ python main.py Camila\n\nHello Camila\n\n// It works! 🎉\n```\n\n\u003c/div\u003e\n\n**Note**: you can also call this same script with the `typer` command, but you don't need to.\n\n## Example upgrade\n\nThis was the simplest example possible.\n\nNow let's see one a bit more complex.\n\n### An example with two subcommands\n\nModify the file `main.py`.\n\nCreate a `typer.Typer()` app, and create two subcommands with their parameters.\n\n```Python hl_lines=\"3  6  11  20\"\nimport typer\n\napp = typer.Typer()\n\n\n@app.command()\ndef hello(name: str):\n    print(f\"Hello {name}\")\n\n\n@app.command()\ndef goodbye(name: str, formal: bool = False):\n    if formal:\n        print(f\"Goodbye Ms. {name}. Have a good day.\")\n    else:\n        print(f\"Bye {name}!\")\n\n\nif __name__ == \"__main__\":\n    app()\n```\n\nAnd that will:\n\n* Explicitly create a `typer.Typer` app.\n    * The previous `typer.run` actually creates one implicitly for you.\n* Add two subcommands with `@app.command()`.\n* Execute the `app()` itself, as if it was a function (instead of `typer.run`).\n\n### Run the upgraded example\n\nCheck the new help:\n\n\u003cdiv class=\"termy\"\u003e\n\n```console\n$ python main.py --help\n\n Usage: main.py [OPTIONS] COMMAND [ARGS]...\n\n╭─ Options ─────────────────────────────────────────╮\n│ --install-completion          Install completion  │\n│                               for the current     │\n│                               shell.              │\n│ --show-completion             Show completion for │\n│                               the current shell,  │\n│                               to copy it or       │\n│                               customize the       │\n│                               installation.       │\n│ --help                        Show this message   │\n│                               and exit.           │\n╰───────────────────────────────────────────────────╯\n╭─ Commands ────────────────────────────────────────╮\n│ goodbye                                           │\n│ hello                                             │\n╰───────────────────────────────────────────────────╯\n\n// When you create a package you get ✨ auto-completion ✨ for free, installed with --install-completion\n\n// You have 2 subcommands (the 2 functions): goodbye and hello\n```\n\n\u003c/div\u003e\n\nNow check the help for the `hello` command:\n\n\u003cdiv class=\"termy\"\u003e\n\n```console\n$ python main.py hello --help\n\n Usage: main.py hello [OPTIONS] NAME\n\n╭─ Arguments ───────────────────────────────────────╮\n│ *    name      TEXT  [default: None] [required]   │\n╰───────────────────────────────────────────────────╯\n╭─ Options ─────────────────────────────────────────╮\n│ --help          Show this message and exit.       │\n╰───────────────────────────────────────────────────╯\n```\n\n\u003c/div\u003e\n\nAnd now check the help for the `goodbye` command:\n\n\u003cdiv class=\"termy\"\u003e\n\n```console\n$ python main.py goodbye --help\n\n Usage: main.py goodbye [OPTIONS] NAME\n\n╭─ Arguments ───────────────────────────────────────╮\n│ *    name      TEXT  [default: None] [required]   │\n╰───────────────────────────────────────────────────╯\n╭─ Options ─────────────────────────────────────────╮\n│ --formal    --no-formal      [default: no-formal] │\n│ --help                       Show this message    │\n│                              and exit.            │\n╰───────────────────────────────────────────────────╯\n\n// Automatic --formal and --no-formal for the bool option 🎉\n```\n\n\u003c/div\u003e\n\nNow you can try out the new command line application:\n\n\u003cdiv class=\"termy\"\u003e\n\n```console\n// Use it with the hello command\n\n$ python main.py hello Camila\n\nHello Camila\n\n// And with the goodbye command\n\n$ python main.py goodbye Camila\n\nBye Camila!\n\n// And with --formal\n\n$ python main.py goodbye --formal Camila\n\nGoodbye Ms. Camila. Have a good day.\n```\n\n\u003c/div\u003e\n\n**Note**: If your app only has one command, by default the command name is **omitted** in usage: `python main.py Camila`. However, when there are multiple commands, you must **explicitly include the command name**: `python main.py hello Camila`. See [One or Multiple Commands](https://typer.tiangolo.com/tutorial/commands/one-or-multiple/) for more details.\n\n### Recap\n\nIn summary, you declare **once** the types of parameters (*CLI arguments* and *CLI options*) as function parameters.\n\nYou do that with standard modern Python types.\n\nYou don't have to learn a new syntax, the methods or classes of a specific library, etc.\n\nJust standard **Python**.\n\nFor example, for an `int`:\n\n```Python\ntotal: int\n```\n\nor for a `bool` flag:\n\n```Python\nforce: bool\n```\n\nAnd similarly for **files**, **paths**, **enums** (choices), etc. And there are tools to create **groups of subcommands**, add metadata, extra **validation**, etc.\n\n**You get**: great editor support, including **completion** and **type checks** everywhere.\n\n**Your users get**: automatic **`--help`**, **auto-completion** in their terminal (Bash, Zsh, Fish, PowerShell) when they install your package or when using the `typer` command.\n\nFor a more complete example including more features, see the \u003ca href=\"https://typer.tiangolo.com/tutorial/\"\u003eTutorial - User Guide\u003c/a\u003e.\n\n## Dependencies\n\n**Typer** stands on the shoulders of a giant. Its only internal required dependency is \u003ca href=\"https://click.palletsprojects.com/\" class=\"external-link\" target=\"_blank\"\u003eClick\u003c/a\u003e.\n\nBy default it also comes with extra standard dependencies:\n\n* \u003ca href=\"https://rich.readthedocs.io/en/stable/index.html\" class=\"external-link\" target=\"_blank\"\u003e\u003ccode\u003erich\u003c/code\u003e\u003c/a\u003e: to show nicely formatted errors automatically.\n* \u003ca href=\"https://github.com/sarugaku/shellingham\" class=\"external-link\" target=\"_blank\"\u003e\u003ccode\u003eshellingham\u003c/code\u003e\u003c/a\u003e: to automatically detect the current shell when installing completion.\n    * With `shellingham` you can just use `--install-completion`.\n    * Without `shellingham`, you have to pass the name of the shell to install completion for, e.g. `--install-completion bash`.\n\n### `typer-slim`\n\nIf you don't want the extra standard optional dependencies, install `typer-slim` instead.\n\nWhen you install with:\n\n```bash\npip install typer\n```\n\n...it includes the same code and dependencies as:\n\n```bash\npip install \"typer-slim[standard]\"\n```\n\nThe `standard` extra dependencies are `rich` and `shellingham`.\n\n**Note**: The `typer` command is only included in the `typer` package.\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n","funding_links":["https://github.com/sponsors/tiangolo"],"categories":["cli","Python","🛠️ Developer Tools","terminal","typehints","CLI Development","📦 Additional Python Libraries"],"sub_categories":["Web \u0026 APIs"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastapi%2Ftyper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastapi%2Ftyper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastapi%2Ftyper/lists"}