Typer en Python : une bibliothèque qui lit les annotations de type
Typer sert à fabriquer des outils en ligne de commande, ces programmes que l'on lance dans un terminal avec des arguments et des options. Sa documentation officielle le présente comme le « petit frère » de FastAPI : le même auteur, Sebastián Ramírez (tiangolo sur GitHub), y applique la même idée. On décrit les paramètres d'une fonction avec des annotations de type Python, et la bibliothèque en déduit l'interface : quels paramètres sont obligatoires, lesquels sont facultatifs, quel type de valeur est attendu, et le texte de l'aide.
Le projet est jeune à l'échelle de Python. Sa toute première version publiée sur PyPI, la 0.0.1, date du 20 décembre 2019. La version 0.27.3, mise en ligne le 6 octobre 2026, demande au minimum Python 3.10. Typer est distribué sous licence MIT, ce qui autorise son usage dans un projet commercial comme dans un script personnel.
Ce que la bibliothèque prend en charge sans code supplémentaire : l'aide automatique avec --help, la conversion des valeurs reçues (un entier reste un entier, un booléen devient un drapeau), les messages d'erreur lisibles quand un argument manque, et l'autocomplétion dans le terminal.
Installer Typer en 2026 : uv, pip et la fin de typer-slim
La page d'accueil du projet recommande désormais le gestionnaire uv : la commande uv add typer ajoute la bibliothèque au projet et installe aussi l'exécutable typer dans l'environnement virtuel. L'installation classique reste possible avec pip install typer, de préférence dans un environnement virtuel créé pour le projet.
Deux changements récents brouillent les anciens tutoriels. D'abord, depuis la version 0.22.0, le paquet typer-slim n'est plus une version allégée : il installe simplement tout Typer. Ensuite, depuis la version 0.26.0, Typer embarque directement le code source de Click, la bibliothèque sur laquelle il est construit, au lieu de l'installer comme dépendance séparée. Un article qui conseille pip install typer[all] ou qui liste Click parmi les dépendances décrit donc une version ancienne.
| Paquet | Rôle selon la documentation |
|---|---|
| rich | mise en forme des erreurs et de l'aide dans le terminal |
| shellingham | détection du shell pour l'autocomplétion |
| annotated-doc | documentation tirée des annotations de type |
| colorama | couleurs dans la console, uniquement sous Windows |
Pour vérifier la version présente sur une machine, pip show typer affiche le numéro installé.
Premier script : une fonction et typer.run()
Le plus petit programme Typer tient en quelques lignes. On importe typer, on écrit une fonction main(name: str) qui affiche un bonjour avec print, puis on termine le fichier par le bloc habituel if __name__ == "__main__": suivi de typer.run(main).
Lancé avec python main.py, sans argument, le script s'arrête et signale qu'un argument NAME manque. Avec python main.py Camille, il affiche le message. Avec python main.py --help, il présente l'usage, l'argument attendu et les options disponibles, alors qu'aucune ligne d'aide n'a été écrite.
C'est là toute la différence avec argparse, le module de la bibliothèque standard : il faut y créer un analyseur, ajouter chaque argument un par un, puis récupérer les valeurs dans un objet. Avec Typer, la signature de la fonction suffit.
Plusieurs commandes avec typer.Typer() et @app.command()
Dès qu'un outil fait plus d'une chose, on passe à une application. On crée un objet app = typer.Typer(), puis on décore chaque fonction avec @app.command(). Le nom de la fonction devient le nom de la sous-commande : hello et goodbye dans l'exemple officiel, appelées avec python main.py hello Camille ou python main.py goodbye Camille. Le script se termine alors par app() au lieu de typer.run(main).
Arguments ou options : la règle à retenir
Typer décide à partir de la signature. Un paramètre sans valeur par défaut devient un argument de ligne de commande, obligatoire et positionnel. Un paramètre avec une valeur par défaut devient une option nommée, précédée de deux tirets. Ainsi, goodbye(name: str, formal: bool = False) produit un argument NAME et une option --formal ; pour un booléen, Typer crée aussi la forme inverse --no-formal.
Préciser l'aide, les valeurs et les noms courts
Pour aller plus loin que le comportement par défaut, on annote le paramètre avec Annotated, du module typing, et on y place typer.Argument() ou typer.Option(). On peut y fixer un texte d'aide, un nom court comme -f, une valeur par défaut ou une variable d'environnement de repli. Les types reconnus vont au-delà de str et int : float, booléens, dates, chemins de fichiers, listes ou choix limités à une énumération.
Dialoguer avec l'utilisateur dans le terminal
Une ligne de commande ne se limite pas aux paramètres passés au lancement. Typer fournit typer.prompt() pour demander une saisie, typer.confirm() pour une question oui ou non, et typer.echo() pour afficher du texte. Une option peut aussi être déclarée avec prompt=True : si l'utilisateur ne la fournit pas, le programme la lui demande au lieu d'échouer. Pour un mot de passe, l'option hide_input évite que la saisie s'affiche.
Pour arrêter proprement un programme, on lève typer.Exit, avec un code de sortie non nul en cas d'erreur, ce que les scripts shell et les outils d'intégration continue savent interpréter.
La commande typer et l'autocomplétion
L'installation ajoute un exécutable du même nom. Selon la page d'accueil, il fait tourner un script comme une application en ligne de commande, même si ce script n'utilise pas Typer : typer main.py run lance les fonctions du fichier et leur donne une aide et une autocomplétion.
L'autocomplétion couvre Bash, Zsh, Fish et PowerShell. Pour un programme installé comme paquet, l'utilisateur l'active une fois avec l'option --install-completion, que Typer ajoute de lui-même ; --show-completion affiche le code correspondant sans l'installer. Les erreurs et l'aide passent par Rich, avec couleurs et encadrés. Dans un environnement où ces couleurs gênent, la variable d'environnement TYPER_USE_RICH réglée à False ou 0 les désactive.
Typer, Click ou argparse : lequel choisir ?
Les trois outils produisent le même résultat final, une commande utilisable dans un terminal. Ils diffèrent par la manière de la décrire.
| Critère | argparse | Click | Typer |
|---|---|---|---|
| Installation | aucune, module standard | paquet à installer | paquet à installer |
| Description des paramètres | appels add_argument() | décorateurs @click.option | annotations de type |
| Aide --help | générée | générée | générée, mise en forme par Rich |
| Autocomplétion | non intégrée | à configurer | option --install-completion |
| Cas typique | script sans dépendance | gros outil existant | nouvel outil typé |
argparse reste le choix logique quand le script doit tourner sur une machine où l'on ne peut rien installer. Typer prend l'avantage dès que l'outil grossit : l'éditeur de code connaît le type de chaque paramètre et signale une erreur avant l'exécution.
Deux petits outils du quotidien écrits avec Typer
Un calcul de paie se prête bien à l'exercice. Une commande paie avec deux options, --taux-horaire en float et --heures en int, multiplie les deux et affiche le brut mensuel. Les valeurs d'une grille de salaire de manager en restauration rapide servent alors de jeu d'essai concret.
Autre usage courant : envoyer un compte rendu par e-mail à la fin d'un traitement. La commande reçoit le destinataire en argument, l'adresse du serveur en option avec une variable d'environnement de repli, et demande le mot de passe avec hide_input. Les paramètres SMTP d'une boîte Zimbra Free sont un exemple des réglages à prévoir.
Ces deux programmes se testent sans ouvrir de terminal grâce à CliRunner, dans le module typer.testing, qui exécute la commande dans un test et vérifie le texte produit et le code de sortie.
Questions fréquentes
Typer est-il gratuit ?
Oui. Typer est publié sous licence MIT, qui permet l'usage, la modification et la redistribution, y compris dans un logiciel commercial.
Quelle version de Python faut-il pour Typer ?
La version 0.27.3 publiée en octobre 2026 demande Python 3.10 ou plus récent. Sur une version plus ancienne, pip installera une version antérieure de Typer, si elle est compatible.
Faut-il encore installer Click à côté de Typer ?
Non. Depuis la version 0.26.0, Typer contient le code source de Click. Il n'apparaît plus dans les dépendances du paquet.
Quelle différence entre typer et typer-slim ?
Il n'y en a plus. Depuis la version 0.22.0, typer-slim installe Typer complet, avec Rich, Shellingham et la commande typer.
Comment désactiver les couleurs de Typer ?
En réglant la variable d'environnement TYPER_USE_RICH à False ou à 0 avant de lancer le programme.
Existe-t-il une documentation de Typer en français ?
La documentation officielle, sur typer.tiangolo.com, est rédigée en anglais. Son tutoriel avance pas à pas, du script d'une fonction jusqu'aux applications à sous-commandes, et chaque exemple peut être copié dans un fichier main.py puis exécuté.
