str.join()

Concatenate an iterable of strings, with the string you call it on as the separator.

String methodPython 2.0+Live demo
Common call
", ".join(["a", "b", "c"])
Returns
new str
Replaces
the separator goes BETWEEN items — not after each one
Watch out
every item must be a str — numbers raise TypeError
str.join(iterableiterable — Any iterable of strings: list, tuple, generator, dict (joins its keys). A single non-str item raises TypeError.type: iterable[str] · required)
→ str

Demo

Live evaluation
Try:
Inputs
sepstrthe separator (receiver)
itemslist[str]comma-separated items
Output
', '.join(['a', 'b', 'c'])
'a, b, c'

The separator is the string you call join on; the items come from the iterable. With one item there is nothing to separate, and with an empty iterable the result is an empty string.

Parameters

NameTypeRequiredDescription
iterableiterable[str]yesAny iterable of strings: list, tuple, generator, dict (joins its keys). A single non-str item raises TypeError.

Return value

str — A new string: the items of the iterable concatenated with the separator between them.

Common patterns

Build a path or URL segment
Cleaner and faster than repeated + concatenation.
url = "/".join(["api", "v2", "users"])
# 'api/v2/users'
The split → transform → join round trip
The idiomatic way to edit words in a sentence.
" ".join(w.capitalize() for w in title.split())
Join non-strings
Convert items first — join refuses anything that is not a str.
", ".join(str(n) for n in [1, 2, 3])
# '1, 2, 3'

Examples

1. Join with a comma
", ".join(["a", "b", "c"])
Returns
'a, b, c'
2. Join with empty separator
"".join(["a", "b", "c"])
Returns
'abc'
3. Single item — no separator
", ".join(["solo"])
Returns
'solo'
4. Empty iterable
", ".join([])
Returns
''

Pitfalls

1. The separator is the receiver, not the argument
Reading it backwards is the classic first-encounter mistake.
Wrong way round
["a", "b"].join(", ")
AttributeError: 'list' object has no attribute 'join'
Fix
", ".join(["a", "b"])
'a, b'
2. Non-string items raise TypeError
join never calls str() for you.
Raises
", ".join([1, 2, 3])
TypeError: sequence item 0: expected str instance
Fix
", ".join(str(n) for n in [1, 2, 3])
'1, 2, 3'
3. Joining a plain string iterates its characters
A str is itself an iterable of 1-character strings.
Surprising
"-".join("abc")
'a-b-c'
Wrap it if you meant one item
"-".join(["abc"])
'abc'

When to use

Use it
  • Combining many pieces — one allocation instead of many
  • Inverse of split in a transform pipeline
  • Building delimited output (CSV-ish lines, paths, slugs)
Reach for something else
  • Two or three known pieces → an f-string reads better
  • Quoted/escaped CSV → csv module
  • Filesystem paths → os.path.join / pathlib

Notes

Complexity
O(total length) — two passes: size, then copy
Return
new str
CPython impl
Objects/unicodeobject.c :: PyUnicode_Join
Memory
Single exact-size allocation — why it beats += in a loop
Thread-safe
Yes — str is immutable

FAQ

Because it works on any iterable — lists, tuples, generators, dict keys — not just lists. Putting it on the separator string covers them all with one method.

History

2.0
Method available on the unified string type.