bytes.ljust()

The name describes where the DATA sits, not where the padding goes. Left-justified data means the padding is on the right — a lifelong source of confusion.

Bytes methodPython 3.0+Live demo
Common call
field.ljust(10)
Returns
a new bytes object at least width long
Replaces
data + fill * (width - len(data)), which goes negative on wide data
Watch out
it pads on the RIGHT; the fill must be exactly one byte
bytes.ljust(width[, fillbyte])
→ bytes

Demo

Live evaluation
Try:
Inputs
sstrdata (encoded as utf-8)
widthinttotal width
fillstrfill byte (one char)
Output
bytes('ab', 'utf-8').ljust(5, bytes('-', 'utf-8'))
b'ab---'

The data stays at the left edge and fill bytes are added on the right until the width is reached. Data that already meets or exceeds the width comes back unchanged — ljust never cuts anything off. Empty data becomes pure fill. The fill must be a single byte, exactly as with center and rjust.

Parameters

NameTypeRequiredDescription
widthintyesMinimum total length. Shorter widths return the data unchanged.
fillbytebytesno (b' ')A bytes object of length exactly 1. Anything else raises TypeError.

Return value

bytes — A new bytes object padded on the right with fillbyte to at least width. Data already that long is returned unchanged.

Common patterns

Fixed-width columns
Left-aligned text columns in a byte-based report.
row = name.ljust(20) + amount.rjust(10)
Pad a record to a fixed size
Legacy formats often require exact field lengths.
field = value.ljust(FIELD_LEN, b'\x00')
Dot leaders
Table-of-contents style alignment.
line = title.ljust(60, b'.') + page

Examples

1. Pad right
b'ab'.ljust(5, b'-')
Returns
b'ab---'
2. Default space
b'ab'.ljust(4)
Returns
b'ab '
3. Exact width
b'abc'.ljust(3, b'-')
Returns
b'abc'
4. Already wide
b'abcdef'.ljust(3)
Returns
b'abcdef'
5. Empty
b''.ljust(3, b'-')
Returns
b'---'
6. Bad fill
b'ab'.ljust(5, b'--')
Returns
TypeError: ljust() argument 2 must be a byte string of length 1, not bytes

Pitfalls

1. ljust pads on the RIGHT
The name refers to where the data is justified, not where the fill goes. Left-justified means left-aligned, so the space is on the right. People reach for ljust wanting left padding and get the opposite.
Wrong side
b'42'.ljust(5, b'0')
b'42000'
rjust pads left
b'42'.rjust(5, b'0')
b'00042'
2. It never truncates
Data longer than the width is returned as-is, so a fixed-width field can silently overflow. Slice first if the width is a hard limit.
Overflows
b'toolong'.ljust(4)
b'toolong'
Slice then pad
b'toolong'[:4].ljust(4)
b'tool'
3. Width counts bytes, not characters
A multi-byte character occupies more of the width than it appears to, so encoded text misaligns.
Off by bytes
'é'.encode().ljust(3, b'-')
b'\xc3\xa9-' # one char, but 2 bytes
Pad text
'é'.ljust(3, '-').encode()
padded by character

When to use

Use it
  • Left-aligned columns in fixed-width byte output
  • Padding a field to a required length
  • Dot leaders and similar alignment
Reach for something else
  • Padding on the LEFT → rjust
  • Text with non-ASCII characters → decode, pad, encode
  • A hard width limit → slice first, since ljust never truncates

Notes

Complexity
O(width) — one allocation and fill
Return
A new bytes object; the original when already wide enough
CPython impl
Objects/bytesobject.c :: stringlib_ljust
Memory
Allocates a buffer of max(len, width)
Thread-safe
Yes — bytes are immutable

FAQ

Because it LEFT-justifies the data — pushes it to the left edge — and whatever space remains is on the right. Think of it as text alignment in a word processor: left-aligned text has ragged space on the right.

b'ab'.ljust(5, b'-')
# b'ab---'

History

3.0
bytes.ljust arrived with the bytes type in the text/binary split.