f-strings and the format mini-language

Programs constantly turn values into text: a total on a receipt, a percentage in a report, a date on a ticket, a variable’s value while you hunt a bug. An f-string does that in one readable line, and the format specification after a colon inside it controls the details: how wide, how many decimals, which separator, which alignment.

Values in text with f-strings

Put f (or F) before the opening quote, and write expressions inside curly braces. Python evaluates each one when the line runs and puts its value into the text:

item = "masala dosa"
price = 85
quantity = 3

# Expressions inside the braces run when the line runs, and their values are put in the text.
print(f"{quantity} × {item} cost {price * quantity}")
print(f"{item.title()} has {len(item)} characters")

# Without the f, braces are ordinary characters.
print("{quantity} × {item}")

# Doubled braces print one brace.
print(f"{{quantity}} is replaced by {quantity}")

3 × masala dosa cost 255
Masala Dosa has 11 characters
{quantity} × {item}
{quantity} is replaced by 3

• Anything that is an expression can go in the braces: a name, arithmetic, a method call such as item.title(). Unless a format specification (the next section) says otherwise, each value appears as str() would write it.
• Forget the f and the braces are printed as typed, with no error to warn you. When you see {name} in your output, look for the missing f first.
• To print a brace itself, double it: {{ and }}.

Format specifications

After the expression, a colon starts a format specification, a short code that says how the value should look. This receipt uses widths, alignment, decimals and commas:

order = [("Masala dosa", 2, 85), ("Filter coffee", 3, 30), ("Idli", 4, 12.5), ("Party thali", 40, 260)]

print(f"{'Item':<15}{'Qty':>5}{'Price':>9}{'Amount':>12}")
total = 0
# Each item is a tuple (name, quantity, price); the loop takes them one at a time.
for name, quantity, price in order:
    amount = quantity * price
    total += amount
    print(f"{name:<15}{quantity:>5}{price:>9.2f}{amount:>12,.2f}")
print(f"{'Total':<29}{total:>12,.2f}")
print(f"{' Thank you ':*^41}")

Item             Qty    Price      Amount
Masala dosa        2    85.00      170.00
Filter coffee      3    30.00       90.00
Idli               4    12.50       50.00
Party thali       40   260.00   10,400.00
Total                           10,710.00
*************** Thank you ***************

The header line formats strings: {'Item':<15} pads “Item” with spaces to 15 characters, aligned left. The item lines format numbers: {price:>9.2f} writes the price with two decimals, right-aligned in 9 characters, and {amount:>12,.2f} adds a comma between every three digits. The last line centres a text with ^ and fills the spare room with *.

Every part of a specification is optional, but the parts that are present always come in this order:

1. Fill and align, such as *>: < left, > right, ^ centre, and = puts the padding after the sign. Any fill character may come before the align character.
2. Sign, such as +: + shows a sign on every number, and a space puts a space before positive numbers.
3. z (Python 3.11 and newer): turns a negative zero after rounding, such as -0.00, into 0.00.
4. #: the alternate form, which adds prefixes such as 0x for hexadecimal.
5. 0: pads numbers with zeros after the sign.
6. Width, such as 12: the minimum width in characters. Longer values are not cut.
7. Grouping, such as ,: a comma (or _) between groups of three digits. With the types b, o, x and X, _ groups in fours instead.
8. Precision, such as .2: the digits after the point for f, e and %, the significant digits for g, and the most characters kept for a string.
9. Type, such as f: how to write the value, for example d, f, e, g, %, x or b.

Without an align character, strings line up on the left and numbers on the right. A width is only a minimum: a value longer than the width is printed in full, which keeps numbers correct but can push a column out of line.

Numbers

format(value, spec) applies one specification and returns the text, exactly as an f-string does after its colon. This program runs a list of specifications through it:

# format(value, spec) applies one format specification; an f-string does the same after the colon.
examples = [
    (1234567.891, ".2f"),
    (1234567.891, ",.2f"),
    (1234567.891, "_.0f"),
    (1234567.891, ".3e"),
    (1234567.891, ".3g"),
    (0.256, ".1%"),
    (42, "+d"),
    (42, "06d"),
    (255, "x"),
    (255, "#X"),
    (5, "08b"),
    (-0.004, ".2f"),
    (-0.004, "z.2f"),
]
for value, spec in examples:
    print(f"{value!r:>11} {spec!r:7} → {format(value, spec)}")

1234567.891 '.2f'   → 1234567.89
1234567.891 ',.2f'  → 1,234,567.89
1234567.891 '_.0f'  → 1_234_568
1234567.891 '.3e'   → 1.235e+06
1234567.891 '.3g'   → 1.23e+06
      0.256 '.1%'   → 25.6%
         42 '+d'    → +42
         42 '06d'   → 000042
        255 'x'     → ff
        255 '#X'    → 0XFF
          5 '08b'   → 00000101
     -0.004 '.2f'   → -0.00
     -0.004 'z.2f'  → 0.00

• f gives a fixed number of decimals and e scientific notation. g picks one of the two and drops zeros at the end; with .3g it keeps three significant digits.
• % multiplies by 100 and adds a percent sign, so store fractions (0.256) rather than percentages.
• d is a whole number, x and X hexadecimal, b binary and o octal; # adds the prefix (0X), and 08b pads with zeros to eight places.
• Rounding to a precision follows the same rules as round(), on the binary value a float really holds, so a few decimal numbers round the “wrong” way; the floating-point lesson explains why. For money, keep whole paise or cents in an integer, or use decimal.Decimal.
• -0.004 rounds to -0.00, which looks odd on a report; the z option writes 0.00 instead.

value = 1234567.891234

print(f"{value:,f}")
print(f"{value:,._f}")
print(f"{value:_._f}")
print(f"{0.000123456789:.10_f}")

1,234,567.891234
1,234,567.891_234
1_234_567.891_234
0.000_123_456_8

A common mistake: the wrong type code

Each type code belongs to some kinds of value. d is for integers, and a float does not convert itself silently:

price = 49.75

# A float with no decimals shown: the f type with precision 0 rounds it.
print(f"{price:.0f}")

# The d type is for integers only, so this line stops the program.
print(f"{price:d}")

50

Traceback (most recent call last):
  File "mistakes.py", line 7, in <module>
    print(f"{price:d}")
            ^^^^^^^^^
ValueError: Unknown format code 'd' for object of type 'float'

{price:.0f} is the way to show a float without decimals (it rounds). For text, only a fill with the alignments <, > and ^, a width, a precision (which cuts the text short) and the type s make sense: {name:,} fails because commas mean nothing for a string.

Dates and times

Dates and times have their own specification language: after the colon come the strftime codes of the datetime module, such as %d for the day, %B for the month’s name and %H:%M for a 24-hour time:

from datetime import datetime

departure = datetime(2030, 3, 14, 6, 5)

# Dates and times take strftime codes after the colon.
print(f"{departure:%d %B %Y, %H:%M}")
print(f"{departure:%a %d %b}")
print(f"{departure:%Y-%m-%d %H:%M}")
print(f"Boarding at {departure:%I:%M %p}")

14 March 2030, 06:05
Thu 14 Mar
2030-03-14 06:05
Boarding at 06:05 AM

%Y-%m-%d gives the international ISO 8601 order, which also sorts correctly as text. The names of days and months come from the current locale. Whatever the computer’s language, a Python program starts with the plain C locale, which uses English names, until it calls locale.setlocale().

Debugging with = and !r

Add = after the expression and the f-string prints the expression’s text, an equals sign and the value. It is the quickest way to look at a few values while you hunt a bug:

total = 1234.5
city = "Pune "

print(f"{total=}")
print(f"{total = :,.2f}")
print(f"{city=}")
print(f"{city!r} has {len(city)} characters")

total=1234.5
total = 1,234.50
city='Pune '
'Pune ' has 5 characters

• The spaces you write around = are kept, so {total = } prints total = ….
• A format specification can follow: {total = :,.2f}.
• Without a specification, = shows the value with repr(), so a string appears in quotes and its trailing space becomes visible. The conversion !r asks for repr() anywhere (and !s for str(), !a for ascii()). Use it whenever spaces, empty strings or the difference between "7" and 7 might matter.

Reading older formatting code

f-strings arrived in Python 3.6, so older code, many libraries and a lot of answers online use the two styles that came before. They print the same result here:

name = "Asha"
score = 0.8765

# printf-style formatting with %, the oldest style.
print("%s scored %.1f%%" % (name, score * 100))

# str.format(), with the same mini-language as f-strings after each colon.
print("{} scored {:.1%}".format(name, score))
print("{0} scored {1:.1%}. Well done, {0}!".format(name, score))
print("{who} scored {mark:.1%}".format(who=name, mark=score))

# The f-string that does the same.
print(f"{name} scored {score:.1%}")

Asha scored 87.6%
Asha scored 87.6%
Asha scored 87.6%. Well done, Asha!
Asha scored 87.6%
Asha scored 87.6%

• printf-style formatting with % puts the values after the string: %s for any value as text, %d for an integer, %.1f for a float with one decimal, and %% for a percent sign. You will meet it in the logging module and in old code. The Python documentation lists its quirks: a single tuple or dictionary as the value is easy to get wrong.
• str.format() uses braces like an f-string, with the values given as arguments: {} takes the next one, {0} a position (which may repeat) and {who} a keyword. After a colon it uses the same mini-language as f-strings. It is still useful when the template is data, such as a message read from a translation file, because an f-string must be written in the code. Use only templates you control: a field such as {0.__class__} reads an attribute of the value it is given.

Key takeaways

• f"…{expression}…" puts the value of each expression into the text when the line runs; without the f, braces are printed as typed.
• After a colon, a format specification controls the text: fill and align, sign, z, #, 0, width, grouping, precision and type, always in that order.
• ,.2f gives two decimals with commas, % a percentage, x and b hexadecimal and binary, and <, > and ^ align within a width; Python 3.14 can also group the digits after the point.
• , always groups in threes; other conventions, such as the Indian grouping in pairs, need your own code.
• {value=} and !r show what a value really is while you debug.
• % formatting and str.format() still appear in older code; format() uses the same mini-language as f-strings.