Question Types¶

The different question types are meant to cover different use cases. The parameters and configuration options are explained in detail for each type. But before we get into to many details, here is a cheatsheet with the available question types:

use Text to ask for free text input
use Password to ask for free text where the text is hidden
use File Path to ask for a file or directory path with autocompletion
use Confirmation to ask a yes or no question
use Select to ask the user to select one item from a beautiful list
use Raw Select to ask the user to select one item from a list
use Checkbox to ask the user to select any number of items from a list
use Autocomplete to ask for free text with autocomplete help

Text¶

questionary.text(default='', validate=None, qmark='?', style=None, multiline=False, instruction=None, lexer=None, **kwargs)[source]¶

Prompt the user to enter a free text message.

This question type can be used to prompt the user for some text input.

Example

>>> import questionary
>>> questionary.text("What's your first name?").ask()
? What's your first name? Tom
'Tom'

This is just a really basic example, the prompt can be customised using the parameters.

Parameters

message (str) – Question text.
default (str) – Default value will be returned if the user just hits enter.
validate (Optional[Any]) –
Require the entered value to pass a validation. The value can not be submitted until the validator accepts it (e.g. to check minimum password length).

This can either be a function accepting the input and returning a boolean, or an class reference to a subclass of the prompt toolkit Validator class.
qmark (str) – Question prefix displayed in front of the question. By default this is a ?.
style (Optional[Style]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.
multiline (bool) – If True, multiline input will be enabled.
instruction (Optional[str]) – Write instructions for the user if needed. If None and multiline=True, some instructions will appear.
lexer (Optional[Lexer]) – Supply a valid lexer to style the answer. Leave empty to use a simple one by default.
kwargs (Any) – Additional arguments, they will be passed to prompt toolkit.

Returns

Question instance, ready to be prompted (using .ask()).

Return type

Question

Password¶

questionary.password(default='', validate=None, qmark='?', style=None, **kwargs)[source]¶

A text input where a user can enter a secret which won’t be displayed on the CLI.

This question type can be used to prompt the user for information that should not be shown in the command line. The typed text will be replaced with *.

Example

>>> import questionary
>>> questionary.password("What's your secret?").ask()
? What's your secret? ********
'secret42'

This is just a really basic example, the prompt can be customised using the parameters.

Parameters

message (str) – Question text.
default (str) – Default value will be returned if the user just hits enter.
validate (Optional[Any]) –
Require the entered value to pass a validation. The value can not be submitted until the validator accepts it (e.g. to check minimum password length).

This can either be a function accepting the input and returning a boolean, or an class reference to a subclass of the prompt toolkit Validator class.
qmark (str) – Question prefix displayed in front of the question. By default this is a ?.
style (Optional[Style]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.
kwargs (Any) –

Returns

Question instance, ready to be prompted (using .ask()).

Return type

Question

File Path¶

questionary.path(default='', qmark='?', validate=None, style=None, only_directories=False, file_filter=None, complete_style=<CompleteStyle.MULTI_COLUMN: 'MULTI_COLUMN'>, **kwargs)[source]¶

A text input for a file or directory path with autocompletion enabled.

Example

>>> import questionary
>>> questionary.path("What's the path to the projects version file?").ask()
? What's the path to the projects version file? ./pyproject.toml
'./pyproject.toml'

This is just a really basic example, the prompt can be customised using the parameters.

Parameters

message (str) – Question text.
default (str) – Default return value (single value).
qmark (str) – Question prefix displayed in front of the question. By default this is a ?.
complete_style (CompleteStyle) – How autocomplete menu would be shown, it could be COLUMN MULTI_COLUMN or READLINE_LIKE from prompt_toolkit.shortcuts.CompleteStyle.
validate (Optional[Any]) –
Require the entered value to pass a validation. The value can not be submitted until the validator accepts it (e.g. to check minimum password length).

This can either be a function accepting the input and returning a boolean, or an class reference to a subclass of the prompt toolkit Validator class.
style (Optional[Style]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.
only_directories (bool) – Only show directories in auto completion
file_filter (Optional[Callable[[str], bool]]) – Optional callable to filter suggested paths. Only paths where the passed callable evaluates to True will show up in the suggested paths. This does not validate the typed path, e.g. it is still possible for the user to enter a path manually, even though this filter evaluates to False. If in addition to filtering suggestions you also want to validate the result, use validate in combination with the file_filter.
kwargs (Any) –

Returns

Question instance, ready to be prompted (using .ask()).

Return type

Question

Confirmation¶

questionary.confirm(default=True, qmark='?', style=None, auto_enter=True, **kwargs)[source]¶

A yes or no question. The user can either confirm or deny.

This question type can be used to prompt the user for a confirmation of a yes-or-no question. If the user just hits enter, the default value will be returned.

Example

>>> import questionary
>>> questionary.confirm("Are you amazed?").ask()
? Are you amazed? Yes
True

This is just a really basic example, the prompt can be customised using the parameters.

Parameters

message (str) – Question text.
default (bool) – Default value will be returned if the user just hits enter.
qmark (str) – Question prefix displayed in front of the question. By default this is a ?.
style (Optional[Style]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.
auto_enter (bool) – If set to False, the user needs to press the ‘enter’ key to accept their answer. If set to True, a valid input will be accepted without the need to press ‘Enter’.
kwargs (Any) –

Returns

Question instance, ready to be prompted (using .ask()).

Return type

Question

Select¶

questionary.select(choices, default=None, qmark='?', pointer='»', style=None, use_shortcuts=False, use_arrow_keys=True, use_indicator=False, use_jk_keys=True, show_selected=False, instruction=None, **kwargs)[source]¶

A list of items to select one option from.

The user can pick one option and confirm it (if you want to allow the user to select multiple options, use questionary.checkbox() instead).

Example

>>> import questionary
>>> questionary.select(
...     "What do you want to do?",
...     choices=[
...         "Order a pizza",
...         "Make a reservation",
...         "Ask for opening hours"
...     ]).ask()
? What do you want to do? Order a pizza
'Order a pizza'

This is just a really basic example, the prompt can be customised using the parameters.

Parameters

message (str) – Question text
choices (Sequence[Union[str, Choice, Dict[str, Any]]]) – Items shown in the selection, this can contain Choice or or Separator objects or simple items as strings. Passing Choice objects, allows you to configure the item more (e.g. preselecting it or disabling it).
default (Union[str, Choice, Dict[str, Any], None]) – A value corresponding to a selectable item in the choices, to initially set the pointer position to.
qmark (str) – Question prefix displayed in front of the question. By default this is a ?.
pointer (Optional[str]) – Pointer symbol in front of the currently highlighted element. By default this is a ». Use None to disable it.
instruction (Optional[str]) – A hint on how to navigate the menu. It’s (Use shortcuts) if only use_shortcuts is set to True, (Use arrow keys or shortcuts) if use_arrow_keys & use_shortcuts are set and (Use arrow keys) by default.
style (Optional[Style]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.
use_indicator (bool) – Flag to enable the small indicator in front of the list highlighting the current location of the selection cursor.
use_shortcuts (bool) – Allow the user to select items from the list using shortcuts. The shortcuts will be displayed in front of the list items. Arrow keys, j/k keys and shortcuts are not mutually exclusive.
use_arrow_keys (bool) – Allow the user to select items from the list using arrow keys. Arrow keys, j/k keys and shortcuts are not mutually exclusive.
use_jk_keys (bool) – Allow the user to select items from the list using j (down) and k (up) keys. Arrow keys, j/k keys and shortcuts are not mutually exclusive.
show_selected (bool) – Display current selection choice at the bottom of list.
kwargs (Any) –

Returns

Question instance, ready to be prompted (using .ask()).

Return type

Question

Raw Select¶

questionary.rawselect(choices, default=None, qmark='?', pointer='»', style=None, **kwargs)[source]¶

Ask the user to select one item from a list of choices using shortcuts.

The user can only select one option.

Example

>>> import questionary
>>> questionary.rawselect(
...     "What do you want to do?",
...     choices=[
...         "Order a pizza",
...         "Make a reservation",
...         "Ask for opening hours"
...     ]).ask()
? What do you want to do? Order a pizza
'Order a pizza'

This is just a really basic example, the prompt can be customised using the parameters.

Parameters

message (str) – Question text.
choices (Sequence[Union[str, Choice, Dict[str, Any]]]) – Items shown in the selection, this can contain Choice or or Separator objects or simple items as strings. Passing Choice objects, allows you to configure the item more (e.g. preselecting it or disabling it).
default (Optional[str]) – Default return value (single value).
qmark (str) – Question prefix displayed in front of the question. By default this is a ?.
pointer (Optional[str]) – Pointer symbol in front of the currently highlighted element. By default this is a ». Use None to disable it.
style (Optional[Style]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.
kwargs (Any) –

Returns

Question instance, ready to be prompted (using .ask()).

Return type

Question

Checkbox¶

questionary.checkbox(choices, default=None, validate=<function <lambda>>, qmark='?', pointer='»', style=None, initial_choice=None, use_arrow_keys=True, use_jk_keys=True, **kwargs)[source]¶

Ask the user to select from a list of items.

This is a multiselect, the user can choose one, none or many of the items.

Example

>>> import questionary
>>> questionary.checkbox(
...    'Select toppings',
...    choices=[
...        "Cheese",
...        "Tomato",
...        "Pineapple",
...    ]).ask()
? Select toppings done (2 selections)
['Cheese', 'Pineapple']

This is just a really basic example, the prompt can be customised using the parameters.

Parameters

message (str) – Question text
choices (Sequence[Union[str, Choice, Dict[str, Any]]]) – Items shown in the selection, this can contain Choice or or Separator objects or simple items as strings. Passing Choice objects, allows you to configure the item more (e.g. preselecting it or disabling it).
default (Optional[str]) – Default return value (single value). If you want to preselect multiple items, use Choice("foo", checked=True) instead.
validate (Callable[[List[str]], Union[bool, str]]) –
Require the entered value to pass a validation. The value can not be submitted until the validator accepts it (e.g. to check minimum password length).

This should be a function accepting the input and returning a boolean. Alternatively, the return value may be a string (indicating failure), which contains the error message to be displayed.
qmark (str) – Question prefix displayed in front of the question. By default this is a ?.
pointer (Optional[str]) – Pointer symbol in front of the currently highlighted element. By default this is a ». Use None to disable it.
style (Optional[Style]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.
initial_choice (Union[str, Choice, Dict[str, Any], None]) – A value corresponding to a selectable item in the choices, to initially set the pointer position to.
use_arrow_keys (bool) – Allow the user to select items from the list using arrow keys.
use_jk_keys (bool) – Allow the user to select items from the list using j (down) and k (up) keys.
kwargs (Any) –

Returns

Question instance, ready to be prompted (using .ask()).

Return type

Question

Autocomplete¶

questionary.autocomplete(choices, default='', qmark='?', completer=None, meta_information=None, ignore_case=True, match_middle=True, complete_style=<CompleteStyle.COLUMN: 'COLUMN'>, validate=None, style=None, **kwargs)[source]¶

Prompt the user to enter a message with autocomplete help.

Example

>>> import questionary
>>> questionary.autocomplete(
...    'Choose ant specie',
...    choices=[
...         'Camponotus pennsylvanicus',
...         'Linepithema humile',
...         'Eciton burchellii',
...         "Atta colombica",
...         'Polyergus lucidus',
...         'Polyergus rufescens',
...    ]).ask()
? Choose ant specie Atta colombica
'Atta colombica'

This is just a really basic example, the prompt can be customised using the parameters.

Parameters

message (str) – Question text
choices (List[str]) – Items shown in the selection, this contains items as strings
default (str) – Default return value (single value).
qmark (str) – Question prefix displayed in front of the question. By default this is a ?
completer (Optional[Completer]) – A prompt_toolkit prompt_toolkit.completion.Completion implementation. If not set, a questionary completer implementation will be used.
meta_information (Optional[Dict[str, Any]]) – A dictionary with information/anything about choices.
ignore_case (bool) – If true autocomplete would ignore case.
match_middle (bool) – If true autocomplete would search in every string position not only in string begin.
complete_style (CompleteStyle) – How autocomplete menu would be shown, it could be COLUMN MULTI_COLUMN or READLINE_LIKE from prompt_toolkit.shortcuts.CompleteStyle.
validate (Optional[Any]) –
Require the entered value to pass a validation. The value can not be submitted until the validator accepts it (e.g. to check minimum password length).

This can either be a function accepting the input and returning a boolean, or an class reference to a subclass of the prompt toolkit Validator class.
style (Optional[Style]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.
kwargs (Any) –

Returns

Question instance, ready to be prompted (using .ask()).

Return type

Question

Printing Formatted Text¶

questionary.print(style=None, **kwargs)¶

Print formatted text.

Sometimes you want to spice up your printed messages a bit, questionary.print() is a helper to do just that.

Example

>>> import questionary
>>> questionary.print("Hello World 🦄", style="bold italic fg:darkred")
Hello World 🦄

Parameters

text (str) – Text to be printed.
style (Optional[str]) – Style used for printing. The style argument uses the prompt toolkit style strings.
kwargs (Any) –

Return type

None