pop()removes a key from the dict and returns the value it held, in one step. It is del d[key] and d[key] combined.
Without a default, a missing key raises KeyError. With a default, such as d.pop(key, None), a missing key simply returns the default and nothing is removed, which makes it the standard "remove if present" idiom.
dict.pop() is an instance method of the built-in dict type: call it on a dictionary with dot notation, such as orders.pop(...). No import is needed.
Syntax
Name the key to remove, and optionally a value to return if it is not there.
python
value = d.pop(key)
value = d.pop(key, default)
Call
What it does
{"a": 1, "b": 2}.pop("a")
Returns 1; the dict becomes {'b': 2}.
{"a": 1}.pop("z", 0)
Returns 0; nothing is removed.
{"a": 1}.pop("z")
Raises KeyError.
Use del d[key] when you do not need the value, and popitem() when you want the last inserted pair without naming a key.
Method signatures
python
dict.pop(key[, default])
# returns: the removed value, or default when key is missing
Parameters
Parameter
Description
key
The key to remove. It must be hashable.
default
Optional. Returned when key is missing, instead of raising KeyError. None is a valid default.
Return Value
Return Value
Description
the removed value
When key existed: the value it held. The key is now gone.
default
When key was missing and a default was given. The dict is unchanged.
Python Examples
Example 1 — Serve Kitchen Orders by Ticket Number
Take one order out of the queue by its ticket number, and handle a ticket that does not exist.
python
orders = {101: "pizza", 102: "salad", 103: "soup"}
served = orders.pop(102)
print(served)
print(orders)
try:
orders.pop(999)
except KeyError:
print("no order 999")
print(orders.pop(999, "nothing to serve"))
Output
salad
{101: 'pizza', 103: 'soup'}
no order 999
nothing to serve
How It Works
Value comes back.orders.pop(102) hands back "salad" so the kitchen knows what to serve.
Key is gone. Ticket 102 no longer appears; the remaining integer keys keep their order.
Strict by default. Ticket 999 does not exist and no default was given, so KeyError is raised and caught.
Soft with a default. Passing a second argument returns it instead of raising.
Example 2 — Rename Fields in a JSON-Like User Record
Move values to new key names in one line each, and drop a field that may or may not exist.
Right side first. In user["email"] = user.pop("mail"), the pop runs before the assignment, so the old key is removed and its value is stored under the new name.
Renamed keys move. Each new key is inserted fresh, so email and full_name land at the end after id.
Remove if present. There is no password key, so pop("password", None) returns None and removes nothing.
Size check. The record still has three fields: id, email, and full_name.
Example 3 — Consume Keyword Options and Report Leftovers
Pop known options out of **options with defaults, so anything left over is an unknown option.
python
def build_url(host, **options):
scheme = options.pop("scheme", "https")
port = options.pop("port", None)
url = f"{scheme}://{host}"
if port is not None:
url += f":{port}"
if options:
print("ignored:", sorted(options))
return url
print(build_url("example.com"))
print(build_url("localhost", scheme="http", port=8000))
print(build_url("example.org", port=443, debug=True, color="red"))