insert(index, element) places element so that it ends up at position index. The item that was there, and every item after it, shifts one place to the right.
The index is clamped, never rejected: a position past the end appends, a negative position counts from the end, and a position before the start inserts at 0. insert() never raises IndexError.
list.insert() is an instance method of the built-in list type: call it on a list with dot notation, such as stops.insert(...). No import is needed.
Syntax
Give the position first and the item second; like the other in-place methods it returns None.
python
lst.insert(index, element)
Call
What it does
["a", "c"].insert(1, "b")
Returns None; the list becomes ['a', 'b', 'c'].
[1, 2].insert(99, 3)
Returns None; the list becomes [1, 2, 3]: past the end means append.
[1, 2, 3].insert(-1, 9)
Returns None; the list becomes [1, 2, 9, 3]: before the last item, not after it.
insert(0, x) adds to the front and insert(len(lst), x) is the same as append(). Every insert shifts the later items, so it gets slower as the list grows; for many front inserts, a collections.deque is the better tool.
Method signatures
python
list.insert(index, element)
# returns: None; element now sits at position index (clamped to the list size)
Parameters
Parameter
Description
index
An integer position. Negative values count from the end; values outside the list are clamped to the start or the end. A float such as 1.5 raises TypeError.
element
Any object, inserted as one item. A list is inserted as a single nested element, just like with append().
Return Value
Return Value
Description
None
Always None. The list is one item longer and the item at index is the new one (when the index was in range).
Python Examples
Example 1 — Slot Urgent Work Into a Task List
Put an outage fix at the very top, lunch in the middle, and sleep at the end with len() as the position.
-1 means before the last. "Museum" goes in front of "Harbor", which stays the final stop.
Too big becomes the end. Index 100 is far past the two-item list, so "Airport" is simply added at the end.
Too small becomes the start. Index -100 is further left than the list goes, so "Depot" becomes the first stop.
No IndexError. Unlike stops[100], which would raise, insert() clamps every position into range.
Example 3 — Insert New Scores Into a Ranked Leaderboard
Find the first lower score and insert in front of it, so the board stays sorted from high to low.
python
def add_score(board, score):
for i, existing in enumerate(board):
if score > existing:
board.insert(i, score)
return i
board.append(score)
return len(board) - 1
leaderboard = [980, 870, 640, 410]
print(add_score(leaderboard, 900))
print(add_score(leaderboard, 100))
print(add_score(leaderboard, 640))
print(leaderboard)
Output
1
5
4
[980, 900, 870, 640, 640, 410, 100]
How It Works
Scan for the slot.enumerate() gives each position, and the loop stops at the first score that the new one beats.
900 goes second. It does not beat 980 but beats 870, so it is inserted at index 1.
Lowest goes last. 100 beats nothing, so the loop finishes and append() adds it at index 5.
Ties go after. A second 640 only beats 410, so it lands behind the existing 640 at index 4. For ascending lists, the bisect module does the same job faster.
Frequently Asked Questions
No. An index past the end simply appends the item, and an index before the start inserts it at position 0.
Call lst.insert(0, item). The new item becomes lst[0] and every other item moves one place to the right.
Because x is placed before the item currently at index -1, which is the last item. Use append(x) to add at the end.
Assign to an empty slice, for example lst[2:2] = ["a", "b"]. insert() itself adds exactly one item per call.
Inserting near the front of a long list is slower than appending, because all later items must shift. For queues that add at both ends, use collections.deque.