note.nkmk.me

Handle Boolean Arguments with argparse in Python

Posted: | Tags: Python

In Python, you can manage command-line arguments using either sys.argv or the argparse module.

While the argparse module offers flexible support for command-line arguments, handling boolean values (True and False) can be unintuitive and requires special attention.

Contents

Note: This article focuses specifically on handling boolean arguments with the argparse module. For general usage, refer to the official tutorial:

The type Parameter in add_argument()

A useful feature of argparse is that you can specify a type for each argument.

You can set the type using the type parameter in add_argument(). For example, if you set type=int, the argument will be automatically converted to an integer. If the input can't be converted, an error is raised.

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('arg_int', type=int)

args = parser.parse_args()
print(args.arg_int)
print(type(args.arg_int))
source: argparse_type_int.py

Run this script from the command line:

$ python argparse_type_int.py 100
100
<class 'int'>
source: argparse_demo.log

The argument 100 is correctly parsed as an integer.

If you pass a value that can’t be converted to an integer, argparse throws an error:

$ python argparse_type_int.py abc
usage: argparse_type_int.py [-h] arg_int
argparse_type_int.py: error: argument arg_int: invalid int value: 'abc'

$ python argparse_type_int.py 1.23
usage: argparse_type_int.py [-h] arg_int
argparse_type_int.py: error: argument arg_int: invalid int value: '1.23'
source: argparse_demo.log

Avoid Using bool as the type Parameter

It may seem that you can handle boolean values using type=bool, just like with int or float, but this doesn’t behave as expected.

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('arg_bool', type=bool)

args = parser.parse_args()
print(args.arg_bool)
print(type(args.arg_bool))
source: argparse_type_bool.py

Run this script from the command line.

$ python argparse_type_bool.py True
True
<class 'bool'>
source: argparse_demo.log

This may appear to work at first glance. However, the behavior becomes problematic when passing other inputs:

$ python argparse_type_bool.py False
True
<class 'bool'>

$ python argparse_type_bool.py abc
True
<class 'bool'>
source: argparse_demo.log

Even when passing 'False' or an arbitrary string, the result is still True.

This happens because the type parameter simply passes the argument string to the function you provide—in this case, bool(). While this makes sense for int() or float(), bool() treats any non-empty string as True.

Notes on bool() Evaluation

bool() returns False for the following values:

All other values—including non-empty strings like 'False' or 'abc'—are evaluated as True.

print(bool('True'))
print(bool('False'))
print(bool('abc'))
# True
# True
# True

print(bool(''))
# False
source: bool_test.py

So when you use type=bool, a string like 'False' is passed to bool() and interpreted as True.

'store_true' or 'store_false' in action

To correctly handle boolean flags in argparse, use the action parameter with either 'store_true' or 'store_false'.

'store_true' and 'store_false' - These are special cases of 'store_const' used for storing the values True and False respectively. In addition, they create default values of False and True respectively: argparse - action — Python 3.13.3 documentation

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('--en', action='store_true')

args = parser.parse_args()
print(args.en)
print(type(args.en))
source: argparse_option_bool.py

Usage:

$ python argparse_option_bool.py --en
True
<class 'bool'>

$ python argparse_option_bool.py
False
<class 'bool'>
source: argparse_demo.log

Here, --en acts as a boolean flag. If the option is provided, the corresponding variable args.en is set to True; otherwise, it defaults to False.

The name --en is just an example—argparse automatically creates a variable like args.en based on the option name.

If you want the default to be True and turn it False when the flag is present, use action='store_false'.

Handle Boolean Positional Arguments with strtobool()

If you want to parse positional command-line arguments as booleans, you can use the strtobool() function, which converts strings to bool values based on their content.

Up to Python 3.11, strtobool() was included in the standard library's distutils.util module. In Python 3.12 and later, since distutils has been removed, it is available via the setuptools package, which is not part of the standard library and must be installed separately (e.g., using pip).

# For Python 3.11 and earlier
from distutils.util import strtobool

# For Python 3.12 and later (requires installing setuptools)
from setuptools._distutils.util import strtobool

The following case-insensitive strings are considered valid inputs:

  • Truthy: 'y', 'yes', 't', 'true', 'on', '1'
  • Falsy: 'n', 'no', 'f', 'false', 'off', '0'

Any other input will result in a ValueError.

True values are y, yes, t, true, on and 1; false values are n, no, f, false, off and 0. Raises ValueError if val is anything else. 9. API Reference - distutils.util.strtobool(val) — Python 3.11.12 documentation

Previously, strtobool() returned 1 or 0 (as integers), but starting with setuptools version 75.3.2 (released on 2025-03-12), it returns True or False.

from setuptools._distutils.util import strtobool

print(strtobool('true'))
print(strtobool('True'))
print(strtobool('TRUE'))
# True
# True
# True

print(strtobool('t'))
print(strtobool('yes'))
print(strtobool('y'))
print(strtobool('on'))
print(strtobool('1'))
# True
# True
# True
# True
# True

print(strtobool('false'))
print(strtobool('False'))
print(strtobool('FALSE'))
# False
# False
# False

print(strtobool('f'))
print(strtobool('no'))
print(strtobool('n'))
print(strtobool('off'))
print(strtobool('0'))
# False
# False
# False
# False
# False

# print(strtobool('abc'))
# ValueError: invalid truth value 'abc'
source: setuptools_strtobool.py

To use it with argparse, pass it directly to the type parameter:

import argparse

from setuptools._distutils.util import strtobool

parser = argparse.ArgumentParser()
parser.add_argument('arg_bool', type=strtobool)

args = parser.parse_args()
print(args.arg_bool)
print(type(args.arg_bool))
source: argparse_type_strtobool.py

String arguments such as true and false can be read as True or False.

$ python argparse_type_strtobool.py true
True
<class 'bool'>

$ python argparse_type_strtobool.py false
False
<class 'bool'>
source: argparse_demo.log

An error occurs for unexpected inputs.

$ python argparse_type_strtobool.py abc
usage: argparse_type_strtobool.py [-h] arg_bool
argparse_type_strtobool.py: error: argument arg_bool: invalid strtobool value: 'abc'
source: argparse_demo.log

Related Categories

Related Articles