list.remove()

Delete the first item equal to value. Mutates in place; raises ValueError if no match.

List methodPython 1.0+Live demo
Common call
colors.remove("red")
Returns
None — the list itself changes
Replaces
a manual index-find + del pattern
Watch out
ValueError if the value is not there; only the FIRST match is removed
list.remove(valuevalue — Item to remove. First occurrence — by equality (==), not identity — is deleted. If not present, ValueError.type: Any · required)
→ None

Demo

Live evaluation
Try:
Inputs
listlistcomma-separated items
valueAnyvalue to remove
Output
['a', 'b', 'c'].remove('b')
None

The demo shows the LIST STATE after removal. Python actually returns None; the meaningful effect is mutation. Only the FIRST equal item is removed — later duplicates stay. A missing value raises ValueError, exactly what Python does.

Parameters

NameTypeRequiredDescription
valueAnyyesItem to remove. First occurrence — by equality (==), not identity — is deleted. If not present, ValueError.

Return value

None — Returns None — the useful effect is mutation. The demo shows the list state after removal.

Common patterns

Guarded remove
Check membership first to avoid the ValueError.
if item in items:
    items.remove(item)
Try / except for "maybe present"
When absence is expected and cheap to swallow.
try:
    items.remove(item)
except ValueError:
    pass
Remove all occurrences
One remove call kills one item. To wipe them all, filter instead.
items = [x for x in items if x != target]

Examples

1. Basic
xs = ["a","b","c"] xs.remove("b") xs
Returns
["a", "c"]
2. First only
xs = ["a","b","a","b"] xs.remove("a") xs
Returns
["b", "a", "b"]
3. Missing raises
xs = ["a","b"] xs.remove("z")
Returns
ValueError: list.remove(x): x not in list
4. Empty raises too
[].remove("x")
Returns
ValueError: list.remove(x): x not in list

Pitfalls

1. Only removes the first match
A single call kills exactly one item. Callers who expect "wipe all" get surprised.
Leaves duplicates
xs = [1, 2, 1, 3, 1]
xs.remove(1)
xs
[2, 1, 3, 1]
Filter for all
xs = [x for x in xs if x != 1]
[2, 3]
2. ValueError on missing value
remove is strict — absence is an error, not a no-op. If missing is expected, guard or catch.
Blow-up
xs = ["a", "b"]
xs.remove("z")
ValueError: list.remove(x): x not in list
Guarded
if "z" in xs:
    xs.remove("z")
no error, no change
3. Removing while iterating
Mutating the list you are looping over shifts remaining items and skips one — a classic silent-bug.
Skips items
xs = [1, 2, 2, 3]
for x in xs:
    if x == 2:
        xs.remove(x)
xs
[1, 2, 3] # second 2 skipped
Iterate a copy or filter
xs = [x for x in xs if x != 2]
[1, 3]

When to use

Use it
  • Deleting a known-present single item
  • Small lists where equality-scan is cheap
  • When you already know the value, not the index
Reach for something else
  • Removing by index → del xs[i] or list.pop(i)
  • Removing all occurrences → list comprehension filter
  • Large lists or hot loops — remove is O(n) per call
  • Mutating while iterating the same list

Notes

Complexity
O(n) — scans until first match, then shifts trailing items down
Return
None; the list is mutated in place
CPython impl
Objects/listobject.c :: list_remove
Memory
In-place; no new list allocated
Thread-safe
Not safe under concurrent mutation of the same list

FAQ

Python favours explicit failure over silent success. If you truly do not care, wrap in try/except or check `in` first.

History

1.0
list.remove has been part of the list type since the earliest days of Python.