Se uma lista é uma linha de caixas numeradas, um dicionário Python é um conjunto de caixas rotuladas. Você pede o que deseja por nome em vez de posição, e é por isso que os dicionários ficam atrás de dados JSON, configuração, caches e grande parte do próprio Python.

Este tutorial começa com o básico e segue para os padrões que desenvolvedores experientes usam todos os dias. Executamos todos os exemplos no Python 3.13 e a saída mostrada vem dessa execução.

O que é um dicionário?

Um dicionário, ou dict, mapeia chaves para valores. Cada chave aparece apenas uma vez e os valores podem ser qualquer coisa, incluindo listas ou outros dicionários.

Desde o Python 3.7, os dicionários mantêm oficialmente a ordem de inserção. Muitos tutoriais mais antigos ainda os chamam de não ordenados, o que não é mais verdade. Para uma comparação mais ampla dos outros tipos, consulte lista Python versus tupla versus conjunto.

As pesquisas são rápidas porque os dicionários usam uma tabela hash. A verificação de uma chave leva aproximadamente o mesmo tempo, quer o dicionário contenha dez itens ou um milhão, enquanto a pesquisa em uma lista fica mais lenta à medida que ela cresce.

Crie um dicionário

user = {"name": "Asha", "age": 31, "city": "Pune"}

empty = {}
from_keywords = dict(name="Asha", age=31)
from_pairs = dict([("a", 1), ("b", 2)])

Os aparelhos encaracolados são a forma mais comum. Uma armadilha: {} cria um dicionário vazio, não um conjunto vazio. Para um conjunto vazio, você precisa de set().

Leia os valores com segurança

Existem duas maneiras de ler um valor, e a diferença é importante quando uma chave pode não existir:

user["name"]                  # 'Asha'
user["email"]                 # KeyError: 'email'

user.get("email")             # None
user.get("email", "not set")  # 'not set'

Use colchetes quando a chave precisar existir, para que uma chave ausente falhe ruidosamente. Use get() quando a ausência for normal, como um campo opcional em uma resposta da API. Para verificar uma chave, use o operador in, que analisa chaves em vez de valores:

"city" in user    # True
"Pune" in user    # False

Adicionar, atualizar e remover

Atribuir a uma chave atualiza-a, se existir, ou adiciona-a, se não existir:

user["age"] = 32
user["email"] = "asha@example.com"
print(user)

# {'name': 'Asha', 'age': 32, 'city': 'Pune', 'email': 'asha@example.com'}

Python oferece várias maneiras de remover itens:

user.pop("city")          # returns 'Pune' and removes it
user.pop("phone", None)   # no error if it is missing
del user["email"]         # removes it, and raises KeyError if missing
user.clear()              # empties the dictionary

Use pop() quando quiser o valor de volta. Passar um padrão como segundo argumento evita um erro quando a chave não está lá. popitem() remove e retorna o par adicionado mais recentemente.

Loop sobre um dicionário

O loop fornece diretamente as chaves. Para obter chaves e valores, use items():

user = {"name": "Asha", "age": 32}

for key, value in user.items():
    print(key, "=", value)

# name = Asha
# age = 32

keys(), values() e items() retornam visualizações ao vivo em vez de cópias, para que reflitam alterações posteriores. Não adicione ou remova chaves durante o loop em um dicionário, porque o Python gera um RuntimeError. Faça um loop em list(user) se precisar fazer isso.

Folha de referências de métodos de dicionário

Mesclar dicionários

Uma necessidade comum é aplicar configurações do usuário sobre os padrões. Quando as chaves se chocam, o lado direito vence:

defaults = {"theme": "light", "lang": "en"}
saved = {"theme": "dark"}

defaults | saved
{**defaults, **saved}

# Both give: {'theme': 'dark', 'lang': 'en'}

O operador | precisa do Python 3.9 ou posterior, enquanto a versão ** também funciona em versões mais antigas. Ambos criam um novo dicionário. Por outro lado, defaults.update(saved) e defaults |= saved mudam defaults de lugar.

Compreensão e classificação

As compreensões de dicionário constroem um novo dicionário em uma única linha legível, assim como as compreensões de lista fazem para listas:

prices = {"pen": 10, "book": 250, "bag": 900}

{k: v for k, v in prices.items() if v > 100}
# {'book': 250, 'bag': 900}

Para classificar por valor, passe uma função key para sorted(). Para encontrar a chave com o maior valor, use max():

sorted(prices.items(), key=lambda item: item[1], reverse=True)
# [('bag', 900), ('book', 250), ('pen', 10)]

max(prices, key=prices.get)
# 'bag'

Um dicionário não possui método sort() e sorted() retorna uma lista de pares. Coloque o resultado em dict() se quiser um dicionário nessa ordem.

Contando e agrupando padrões

Duas tarefas surgem constantemente. A primeira é a contagem, que você pode fazer usando get() com o padrão zero:

words = "to be or not to be".split()

counts = {}
for word in words:
    counts[word] = counts.get(word, 0) + 1

print(counts)
# {'to': 2, 'be': 2, 'or': 1, 'not': 1}

A biblioteca padrão torna isso ainda mais curto com Counter:

from collections import Counter

Counter(words).most_common(2)
# [('to', 2), ('be', 2)]

O segundo é o agrupamento, e defaultdict é ideal aqui porque cria o valor que falta para você:

from collections import defaultdict

orders = [("Asha", 1200), ("Ben", 300), ("Asha", 800)]

by_customer = defaultdict(list)
for name, total in orders:
    by_customer[name].append(total)

print(dict(by_customer))
# {'Asha': [1200, 800], 'Ben': [300]}

Sem ele, você precisaria verificar se cada chave existe antes de anexar. Esses mesmos padrões funcionam bem para agregar dados de API ou linhas de log. Quando um dicionário está vazio ou uma chave está faltando, nosso guia para tratamento de exceções em Python mostra como lidar com o resultado KeyError.

Dados aninhados e a armadilha de cópia

JSON mapeia diretamente para dicionários e listas aninhados, portanto, você frequentemente encadeará chaves. O encadeamento get() mantém isso seguro quando um nível pode estar faltando:

response = {"user": {"profile": {"city": "Pune"}}}

response["user"]["profile"]["city"]               # 'Pune'
response.get("user", {}).get("settings", {}).get("theme")   # None

Tenha cuidado ao copiar dados aninhados. copy() duplica apenas o nível superior, portanto os dicionários internos permanecem compartilhados com o original:

settings = {"db": {"host": "localhost"}}

shallow = settings.copy()
shallow["db"]["host"] = "prod"

print(settings["db"]["host"])
# prod

Alterar a cópia alterou o original, o que pode ser um bug desagradável. Use copy.deepcopy(settings) para obter uma cópia totalmente independente.

O que pode ser uma chave de dicionário?

As chaves devem ser hashable, o que geralmente significa imutável. Strings, números e tuplas de valores imutáveis ​​funcionam. Listas e dicionários não:

{["a"]: 1}

# TypeError: unhashable type: 'list'

A razão é que o hash de uma chave decide onde seu valor é armazenado. Se uma chave pudesse mudar, o Python não seria mais capaz de encontrá-la. Se você precisar de uma chave composta, use uma tupla, como {("Pune", 2026): 120}.

Erros comuns

• Usando colchetes em chaves opcionais. Use get() quando uma chave estiver ausente.
• Assumir que get() significa que a chave existe. None pode significar que está ausente ou armazenada None. Use in quando a diferença for importante.
• Usando um padrão mutável. dict.fromkeys(names, []) dá a cada chave a mesma lista. Em vez disso, use uma compreensão.
• Alterando o tamanho durante a iteração. Faça um loop sobre uma cópia das chaves.
• Usando um dict para campos conhecidos e fixos. Um dataclass pode ser mais claro e detecta erros de digitação em nomes de campos.

Considerações finais

Os dicionários recompensam um pouco de prática. Lembre-se de get() para chaves opcionais, items() para loops e Counter e defaultdict para os dois trabalhos mais comuns. Para praticar, pegue um pequeno arquivo JSON e escreva um código para contar e agrupar seus registros. Se você é novo na linguagem, comece com nosso tutorial Python para iniciantes.

Perguntas frequentes

Continue aprendendo