Skip to main content

How to Append Values to a List as Dictionary Value

Standard Python dictionaries map a unique key to a single value. However, a common requirement in data processing (such as grouping items by category or tracking user logs) is to associate a single key with multiple values. The standard solution is to use a list as the dictionary value.

This guide explains how to safely append items to a list stored within a dictionary, handling cases where the key might not exist yet.

Problem: The KeyError Trap​

If you try to append to a list associated with a key that does not exist in the dictionary yet, Python raises a KeyError. You cannot append to a list that hasn't been created.

fruit_basket = {}

try:
    # ⛔️ Incorrect: 'apples' does not exist yet, so we cannot access it to append
    fruit_basket['apples'].append('Granny Smith')
except KeyError as e:
    print(f"Error: {e}")

Output:

Error: 'apples'

To fix this, you must ensure the list exists before you append to it.

Method 1: The if-else Check (Manual Approach)​

The most explicit way to handle this is to check if the key exists. If it doesn't, create a new list for that key; otherwise, append to the existing list.

fruit_basket = {
    'apples': ['Red Delicious']
}

new_item = 'Granny Smith'
category = 'apples'
new_category = 'bananas'

# ✅ Check if key exists
if category not in fruit_basket:
    fruit_basket[category] = []
fruit_basket[category].append(new_item)

# ✅ Handling a new key
if new_category not in fruit_basket:
    fruit_basket[new_category] = []
fruit_basket[new_category].append('Cavendish')

print(fruit_basket)

Output:

{'apples': ['Red Delicious', 'Granny Smith'], 'bananas': ['Cavendish']}

Method 2: Using setdefault() (Built-in Approach)​

Python dictionaries have a built-in method called .setdefault(key, default). It returns the value for the key if it exists; if not, it inserts the key with the default value and returns that default.

This allows you to initialize and append in a single line of code.

user_logs = {}

# ✅ Using setdefault to initialize an empty list if 'user_1' is missing
# Then immediately appending to the returned list
user_logs.setdefault('user_1', []).append('login')
user_logs.setdefault('user_1', []).append('logout')

# Doing the same for a new user
user_logs.setdefault('user_2', []).append('login')

print(user_logs)

Output:

{'user_1': ['login', 'logout'], 'user_2': ['login']}
note

setdefault is concise, but it constructs the default value (the empty list []) every time it is called, even if the key already exists. For extremely high-performance loops, this might be slightly less efficient than Method 3.

For scenarios where you are frequently grouping data or appending to lists, the defaultdict from the collections module is the most Pythonic and efficient solution.

When you access a missing key in a defaultdict, it automatically creates a new value using the factory function you provided (in this case, list).

from collections import defaultdict

# ✅ Initialize defaultdict with 'list' as the factory
# This means any new key will start as an empty list []
products_by_category = defaultdict(list)

# Adding items (No need to check if key exists!)
products_by_category['Electronics'].append('Laptop')
products_by_category['Electronics'].append('Mouse')
products_by_category['Clothing'].append('T-Shirt')

print(dict(products_by_category)) # Converting back to dict for clean display

Output:

{'Electronics': ['Laptop', 'Mouse'], 'Clothing': ['T-Shirt']}
tip

defaultdict(list) eliminates the need for if statements or setdefault. It is the standard tool for grouping algorithms in Python.

Conclusion​

To append values to a list inside a dictionary:

  1. Use collections.defaultdict(list) for the cleanest, most efficient code when aggregating data.
  2. Use dict.setdefault(key, []).append(val) for one-off operations on standard dictionaries without importing modules.
  3. Use if key not in dict checks if you need specific logic during the creation of the new entry.

Table of Contents