Python List extend() Method
list.extend(iterable) adds every item of an iterable (list, tuple, string, set, range...) to the end of the list, changes the list in place and returns None.Reach for extend() when you already have a collection of values and want them all added to an existing list, for example merging today's orders into a running list of orders. It is the bulk version of list.append(), which adds exactly one item.
Because extend() accepts any iterable, you can pass a list, a tuple, a string, a range() or even a generator. Python walks through it and adds each element one by one. See Python list methods for the full set of list tools.
| Syntax | my_list.extend(iterable) |
|---|---|
| Parameters | iterable: any iterable object whose items are added |
| Returns | None (the list is modified in place) |
| Time complexity | O(k), where k is the number of items added |
How list.extend() adds items from an iterable
extend() loops over the argument and appends each element to the end of the list, in the order the iterable produces them. The original list object is changed, so every variable that refers to it sees the new items.
morning = ["tea", "toast"]
morning.extend(["eggs", "juice"])
print(morning)
morning.extend(("jam",))
print(morning)extend() vs append() vs the + operator
The three tools look similar but behave differently when you add a list to a list. append() keeps the second list as one nested item, extend() unpacks it, and + builds a brand new list instead of changing the old one. Use += if you want the in-place behaviour of extend() with operator syntax; for lists, a += b works like a.extend(b).
| Tool | Result for a = [1] and b = [2, 3] | Changes a in place? |
|---|---|---|
a.append(b) | [1, [2, 3]] | Yes |
a.extend(b) | [1, 2, 3] | Yes |
a + b | [1, 2, 3] (new list) | No |
a += b | [1, 2, 3] | Yes |
Strings, dictionaries and other iterables passed to extend()
Anything iterable works, and what you get depends on what the iterable produces. A string produces single characters, so extend("abc") adds 'a', 'b', 'c'. A dictionary produces its keys, and a set produces its items in an arbitrary order, so avoid relying on that order. Extending a list with itself is allowed too and duplicates the contents. For performance, extend() is usually faster than calling append() in a loop because the work happens inside Python's C code; see Python for loops if you want the loop version.
Examples you can run
Press Run, then edit the code and run it again.
Merge two lists of scores
Add a second batch of scores to the first one.
scores = [72, 85]
new_scores = [90, 64, 78]
scores.extend(new_scores)
print(scores)
print(len(scores))Expected output[72, 85, 90, 64, 78]
5
Extend with a string, a range and a dictionary
Each iterable contributes the items it yields: characters, numbers and dictionary keys.
items = []
items.extend("hi")
items.extend(range(3))
items.extend({"x": 1, "y": 2})
print(items)Expected output['h', 'i', 0, 1, 2, 'x', 'y']
Collect items from several carts
A realistic use: gather the contents of many lists into one.
carts = [["pen", "book"], ["lamp"], ["mug", "pen"]]
all_items = []
for cart in carts:
all_items.extend(cart)
print(all_items)Expected output['pen', 'book', 'lamp', 'mug', 'pen']
Common mistakes
Passing a single number
✗ Wrong
nums = [1, 2]
nums.extend(3)✓ Right
nums = [1, 2]
nums.append(3)
print(nums)extend() needs an iterable. To add one value use append(3), or wrap it in a list: extend([3]).
Using the return value
✗ Wrong
a = [1]
b = a.extend([2, 3])
print(b)✓ Right
a = [1]
a.extend([2, 3])
print(a)extend() modifies a and returns None. Use a afterwards, or use a + [2, 3] to get a new list.
Extending with a string by accident
✗ Wrong
names = ["Asha"]
names.extend("Ravi")
print(names)✓ Right
names = ["Asha"]
names.extend(["Ravi"])
print(names)A string is iterable, so its characters are added one by one. Pass a list to add the whole word.
Python List extend() Method: questions people ask
What is the difference between append() and extend() in Python?
append() adds its argument as a single item, while extend() adds each item of an iterable separately. [1].append([2, 3]) gives [1, [2, 3]], but [1].extend([2, 3]) gives [1, 2, 3].
Does extend() return a new list?
No. extend() changes the list in place and returns None, so never write x = x.extend(...).
Can I extend a list with a tuple or a set?
Yes, because any iterable works. Tuples keep their order; sets have no guaranteed order, so sort first if order matters.
Keep learning
Step-by-step lessons:
Python ListsPython List Methods
Related:
Python List append() MethodPython List insert() MethodPython List MethodsPython List copy() Method
More in list methods:
Python List append() MethodPython List insert() MethodPython List remove() MethodPython List pop() MethodPython List clear() MethodPython List index() MethodPython List count() MethodPython List sort() Method See all →