Change a key name in a dictionary in Python

This article explains how to change a key name, i.e., rename a key, in a dictionary (dict) in Python.

To change a value in a dictionary, just specify the key and assign a new value. See the following article for details.

• Merge multiple dictionaries and add items to a dictionary in Python

Add a new item and then remove the old one

Since dict does not provide a method to directly rename a key, you need to add a new item with the new key and original value, then remove the old item.

For more information on how to remove an item from a dictionary, see the following article.

• Remove an item from a dictionary in Python (clear, pop, popitem, del)

With the del statement

If you use the del statement, you can achieve this as follows.

d = {'k1': 1, 'k2': 2, 'k3': 3}

d['k10'] = d['k1']
del d['k1']

print(d)
# {'k2': 2, 'k3': 3, 'k10': 1}

With the pop() method

The pop() method can be used to remove an item and get its value at the same time.

d = {'k1': 1, 'k2': 2, 'k3': 3}

print(d.pop('k1'))
# 1

print(d)
# {'k2': 2, 'k3': 3}

Using pop() is simpler than using del because it allows you to remove an item and get its value in a single step.

d = {'k1': 1, 'k2': 2, 'k3': 3}

d['k10'] = d.pop('k1')

print(d)
# {'k2': 2, 'k3': 3, 'k10': 1}

Note that, by default, an error occurs if a non-existent key is specified as the first argument of pop().

d = {'k1': 1, 'k2': 2, 'k3': 3}

# print(d.pop('k10'))
# KeyError: 'k10'

If the second argument of pop() is specified, it returns the value without error. The original dictionary object remains unchanged.

print(d.pop('k10', None))
# None

print(d)
# {'k1': 1, 'k2': 2, 'k3': 3}

The second argument of pop() can be used to set a default value if you try to change a key that does not exist. It is used in the function described next.

Define a function to change a key name in a dictionary

Here are some examples of functions to change a key name in a dictionary.

If the old key does not exist, add a new item

For example, you can define the following function using pop().

The first argument is the target dictionary, the second is the old key, and the third is the new key.

def change_dict_key(d, old_key, new_key, default_value=None):
    d[new_key] = d.pop(old_key, default_value)

d = {'k1': 1, 'k2': 2, 'k3': 3}
change_dict_key(d, 'k1', 'k10')
print(d)
# {'k2': 2, 'k3': 3, 'k10': 1}

If a non-existent key is specified as the second argument (old key), a new item is added with the new key and the value specified in the fourth argument (None by default).

d = {'k1': 1, 'k2': 2, 'k3': 3}
change_dict_key(d, 'k10', 'k100')
print(d)
# {'k1': 1, 'k2': 2, 'k3': 3, 'k100': None}

d = {'k1': 1, 'k2': 2, 'k3': 3}
change_dict_key(d, 'k10', 'k100', 100)
print(d)
# {'k1': 1, 'k2': 2, 'k3': 3, 'k100': 100}

If an existing key is specified as the third argument (new key), the value of the existing key is overwritten.

d = {'k1': 1, 'k2': 2, 'k3': 3}
change_dict_key(d, 'k1', 'k2')
print(d)
# {'k2': 1, 'k3': 3}

If you want to keep the original value when specifying an existing key as a new key, use the setdefault() method.

• Add an item if the key does not exist in dict with setdefault in Python

def change_dict_key_setdefault(d, old_key, new_key, default_value=None):
    d.setdefault(new_key, d.pop(old_key, default_value))

d = {'k1': 1, 'k2': 2, 'k3': 3}
change_dict_key_setdefault(d, 'k1', 'k2')
print(d)
# {'k2': 2, 'k3': 3}

If the new key does not already exist, the behavior is the same as that of the first function.

d = {'k1': 1, 'k2': 2, 'k3': 3}
change_dict_key_setdefault(d, 'k1', 'k10')
print(d)
# {'k2': 2, 'k3': 3, 'k10': 1}

d = {'k1': 1, 'k2': 2, 'k3': 3}
change_dict_key_setdefault(d, 'k10', 'k100')
print(d)
# {'k1': 1, 'k2': 2, 'k3': 3, 'k100': None}

If the old key does not exist, do nothing

If you want the function to do nothing when the specified key does not exist, use the in operator.

• The in operator in Python (for list, string, dictionary, etc.)

def change_dict_key_exist(d, old_key, new_key):
    if old_key in d:
        d[new_key] = d.pop(old_key)

d = {'k1': 1, 'k2': 2, 'k3': 3}
change_dict_key_exist(d, 'k1', 'k10')
print(d)
# {'k2': 2, 'k3': 3, 'k10': 1}

d = {'k1': 1, 'k2': 2, 'k3': 3}
change_dict_key_exist(d, 'k10', 'k100')
print(d)
# {'k1': 1, 'k2': 2, 'k3': 3}

If an existing key is specified as the third argument (new key), the value of the existing key is overwritten.

d = {'k1': 1, 'k2': 2, 'k3': 3}
change_dict_key_exist(d, 'k1', 'k2')
print(d)
# {'k2': 1, 'k3': 3}

As in the previous example, if you want to keep the original value when specifying an existing key as a new key, use the setdefault() method.

def change_dict_key_exist_setdefault(d, old_key, new_key):
    if old_key in d:
        d.setdefault(new_key, d.pop(old_key))

d = {'k1': 1, 'k2': 2, 'k3': 3}
change_dict_key_exist_setdefault(d, 'k1', 'k2')
print(d)
# {'k2': 2, 'k3': 3}