list.insert()
Inserts an item at a specific index (mutates the list).
my_list.insert(index, item)This static page keeps the syntax and examples indexed for search, while the coding app handles interactive exploration and saved references.
What it does
Overview
Inserts an item at a specific index (mutates the list).
The list.insert() method is used to add a single element into a list at a specified integer index. Unlike append(), which adds items to the end, insert() allows for precise placement. When an item is inserted, all subsequent elements are shifted one position to the right to accommodate the new value. In terms of performance, insert() has a time complexity of O(n) because Python lists are implemented as dynamic arrays; inserting at the beginning (index 0) requires moving every existing element in memory. The method operates in-place, meaning it modifies the original list object and returns None. It is robust with regards to index ranges: providing an index larger than the list length will result in an append, and negative indices count backward from the end of the list. However, users should note that insert(-1, value) places the item before the current last element, not at the absolute end.
Quick reference
Syntax
my_list.insert(index, item)Inputs
Parameters
See it in practice
Examples
Basic Insertion at a Specific Index
fruits = ['apple', 'banana', 'cherry']
fruits.insert(1, 'orange')
print(fruits)['apple', 'orange', 'banana', 'cherry']
Inserts 'orange' at index 1, moving 'banana' and 'cherry' to the right.
Using Negative Indexing
numbers = [10, 20, 40]
numbers.insert(-1, 30)
print(numbers)[10, 20, 30, 40]
Inserts 30 at the position of the last element (-1), shifting the current last element to the right.
Handling Out-of-Bounds Indices
data = ['A', 'B']
data.insert(100, 'Z')
data.insert(-100, 'Start')
print(data)['Start', 'A', 'B', 'Z']
Indices exceeding the list size append to the end, while extreme negative indices insert at the front (index 0).
Debug faster
Common Errors
LogicError
Cause: The method modifies the list in-place and returns None. Assigning the result back to the variable overwrites the list with None.
Fix: Call insert() on its own line without assignment.
my_list = [1, 2]
my_list = my_list.insert(0, 0) # my_list is now NoneTypeError
Cause: insert() accepts exactly two arguments: the index and the object. Trying to insert multiple items directly will fail.
Fix: Use a loop or slice assignment [index:index] = [item1, item2] to insert multiple values.
my_list = [1, 4]
my_list.insert(1, 2, 3) # Raises TypeErrorRuntime support
Compatibility
Source: MDN Web Docs
Common questions
Frequently Asked Questions
Inserts an item at a specific index (mutates the list).
index: Position to insert before (can be <=0 or >len). item: Item to insert.
LogicError: Call insert() on its own line without assignment. TypeError: Use a loop or slice assignment [index:index] = [item1, item2] to insert multiple values.