Python List insert() Method
list.insert(index, item) puts item before the position index, shifts the later items one place to the right, changes the list in place and returns None.While append() always adds at the end, insert() lets you choose where the new item goes. Use it to put a value at the front of a queue, to keep a short list in a particular order or to place a header before the data.
The index works like the index you use in slicing: 0 is the first position and negative numbers count from the end. Unlike reading with my_list[i], insert() never raises an IndexError for an index that is too large or too small.
| Syntax | my_list.insert(index, item) |
|---|---|
| Parameters | index: position to insert before; item: the object to insert |
| Returns | None (the list is modified in place) |
| Time complexity | O(n), because later items must shift |
How list.insert() chooses the position
The new item ends up at index, and the item that used to be there moves right together with everything after it. So insert(0, x) places x first and insert(1, x) places it second.
letters = ["a", "c", "d"]
letters.insert(1, "b")
print(letters)
letters.insert(0, "start")
print(letters)Negative and out-of-range indexes in insert()
A negative index counts from the end, but remember that the item goes before that position. So insert(-1, x) places x just before the last item, not after it. An index larger than the length simply appends the item at the end, and a very negative index inserts at the front. No error is raised in either case.
| Call on [10, 20, 30] | Result |
|---|---|
insert(0, 5) | [5, 10, 20, 30] |
insert(2, 25) | [10, 20, 25, 30] |
insert(-1, 25) | [10, 20, 25, 30] |
insert(99, 40) | [10, 20, 30, 40] |
insert(-99, 0) | [0, 10, 20, 30] |
insert() performance and better choices for queues
Inserting near the front is slow for long lists, because Python has to move every following item. For a handful of items that does not matter. If you repeatedly add to or remove from the front of a large collection, use collections.deque, which handles both ends in constant time. To add several items at a position at once, assign to a slice such as items[1:1] = ["x", "y"]. For plain additions at the end, append() and extend() are the right tools.
Examples you can run
Press Run, then edit the code and run it again.
Insert at the front and in the middle
Add a student to a roll call list at two different positions.
roll = ["Asha", "Dev", "Meera"]
roll.insert(0, "Zoya")
roll.insert(2, "Ravi")
print(roll)Expected output['Zoya', 'Asha', 'Ravi', 'Dev', 'Meera']
Index larger than the list
An index past the end does not fail; the item is added last.
cart = ["pen", "book"]
cart.insert(10, "lamp")
print(cart)
cart.insert(-1, "mug")
print(cart)Expected output['pen', 'book', 'lamp']
['pen', 'book', 'mug', 'lamp']
Keep a list sorted while inserting
Find the right position with a loop, then insert there.
scores = [55, 70, 90]
new = 80
pos = 0
while pos < len(scores) and scores[pos] < new:
pos += 1
scores.insert(pos, new)
print(scores)Expected output[55, 70, 80, 90]
Common mistakes
Swapping the arguments
✗ Wrong
tasks = ["read", "write"]
tasks.insert("plan", 0)✓ Right
tasks = ["read", "write"]
tasks.insert(0, "plan")
print(tasks)The index comes first, then the item: insert(0, "plan").
Expecting insert(-1, x) to add at the end
✗ Wrong
nums = [1, 2, 3]
nums.insert(-1, 99)
print(nums)✓ Right
nums = [1, 2, 3]
nums.append(99)
print(nums)The item goes before the position. To add at the very end use append(99) or insert(len(nums), 99).
Using the return value
✗ Wrong
a = [1, 3]
a = a.insert(1, 2)
print(a)✓ Right
a = [1, 3]
a.insert(1, 2)
print(a)insert() returns None; call it on its own line.
Python List insert() Method: questions people ask
How do I add an element at the beginning of a list in Python?
Use my_list.insert(0, item). For very large lists that you change at the front often, a collections.deque with appendleft() is faster.
What happens if the index in insert() is out of range?
Nothing bad: Python does not raise an error. An index past the end appends the item, and a very negative index inserts it at the front.
What is the difference between insert() and append()?
append() always adds at the end, while insert() adds at any index you choose and moves the later items to the right.
Keep learning
Step-by-step lessons:
Python ListsPython List MethodsPython Slicing
Related:
Python List append() MethodPython List extend() MethodPython List pop() MethodPython List remove() Method
More in list methods:
Python List append() MethodPython List extend() MethodPython List remove() MethodPython List pop() MethodPython List clear() MethodPython List index() MethodPython List count() MethodPython List sort() Method See all →