Skip to content



Before delving into the documentation, examples and code reference, it is first necessary to explore and understand why you may want to use this package.


The design goals of pydantic-argparse are summarised by these core tenets.


pydantic-argparse has a simple API and code-base.


pydantic-argparse is deliberately limited with one way of doing things.


pydantic-argparse fully supports type-hinting and mypy.


There are many benefits to using pydantic-argparse over a more traditional argument parsing package that uses a functional api. Some of the most valuable benefits are outlined below.

Declarative Arguments

Arguments are defined declaratively using pydantic models. This means the command-line interface for your application has a strict schema, that is easy to view, modify or even export to other formats such as JSON Schema.

Familiar Syntax

Due to the use of pydantic models and standard type-hinting, there is almost no new syntax or API to learn. Just declare your interface with a dataclass-like pydantic model, and let pydantic-argparse parse your arguments.

Type Hints

Due to the use of pydantic models, your parsed command-line arguments are just an instance of a type-hinted class. This means that your arguments can support auto-completion, linting, mypy and other tools in your IDE.

Pydantic Validation

Due to the use of pydantic models, your command-line interface is able to heavily leverage pydantic's validation system to provide a very large number of different types.


As a result of type-hinting and pydantic validation, you can have the confidence that once your command-line arguments have been parsed, their type and validity have been confirmed - you don't have to check or worry about them again.


There are also some drawbacks to using pydantic-argparse, depending on the size of your project, the features you require and the programming paradigms that you agree with. Some of the possible drawbacks are outlined below.

Extra Dependencies

While pydantic-argparse itself depends only on pydantic, it has a number of transient dependencies due to the dependencies of pydantic itself. If your application is small, it may not be suitable to pull in pydantic and its dependencies for a simple command-line interface.

Opinionated Design

pydantic-argparse is a very opinionated package by design. It aims for a simple API, and to be both full featured while limiting excessive choices. For example, there are no positional arguments in pydantic-argparse; only optional and required arguments. If your opinions do not align with these design choices, then you may not want to use the package.

Nested Models

Sub-commands are supported by nesting pydantic models. This means that for each sub-command, an additional model must be defined. If your application requires many different sub-commands, it may result in a large number of pydantic models.


There are many alternative argument parsing packages that already exist for Python. Some of the most popular are outlined below.


argparse is a standard-library module that makes it easy to write user-friendly command-line interfaces. The program defines what arguments it requires, and argparse will figure out how to parse those out of sys.argv. The argparse module also automatically generates help and usage messages and issues errors when users give the program invalid arguments.


click is a Python package for creating beautiful command line interfaces in a composable way with as little code as necessary. It’s the “Command Line Interface Creation Kit”. It’s highly configurable but comes with sensible defaults out of the box.


typer is a library for building CLI applications that users will love using and developers will love creating. Based on Python 3.6+ type hints. The key features are that it is intuitive to write, easy to use, short and starts simple but can grow large. It aims to be the fastapi of command-line interfaces.


A feature comparison matrix of the alternatives outlined above is shown below.

argparse click typer pydantic-argparse
Optional Arguments ✅ ✅ ✅ ✅
Required Arguments ✅ ✅ ✅ ✅
Positional Arguments ✅ ✅ ✅
Sub-Commands ✅ ✅ ✅ ✅
Argument Types
Regular Arguments ✅ ✅ ✅ ✅
Variadic Arguments ✅ ✅ ✅ ✅
Flag Arguments ✅ ✅ ✅ ✅
Choice Arguments ✅ ✅ ✅ ✅
Type Validation ✅ ✅ ✅ ✅
Automatic Validation ✅ ✅
Pydantic Validation ✅
Design Pattern
Functional Definition ✅ ✅ ✅
Declarative Definition ✅
Function Decorators ✅ ✅
Function Signature Inspection ✅
Extra Features
Typing Hinting ✅ ✅ ✅
Shell Completion ✅ ✅
Environment Variables ✅ ✅ ✅ ✅