Elisp: Hash Table

By Xah Lee. Date: 2008-01-30. Last updated: 2025-10-10.

What is Hash Table

Hash table is a collection of key-value pairs.

Emacs lisp has 2 types of collection of key-value pairs.

Hash Table → Unordered set of key val pairs. No duplicate keys. Constant access time.
Association List (aka alist) → A ordered list of key val pairs. Keys may repeat. Slow for random access.

Create Hash Table

make-hash-table

(make-hash-table :test 'equal)

Returns a new hashtable.

Key or Value can be any lisp object (any type). Key type should be the same for all keys.

The :test 'equal is to specify what test to check key match. 3 possible choices are:

'eql (the default.)
'eq
'equal

Elisp: Equality Test

🛑 WARNING: you cannot use string-equal

💡 TIP:
For string keys, use 'equal.
For symbol or integer keys, use 'eq.
For floating number keys, use 'eql.

if you want to use a different test, you have to write one by define-hash-table-test. See elisp manual.

There are more options for make-hash-table . See elisp manual.

;; create a hash table
(setq xx (make-hash-table :test 'equal))

Example. Create Hashtable, with String Keys

(progn
  (setq xx (make-hash-table :test 'equal))
  (puthash "a" 1 xx)
  (puthash "b" 2 xx)
  (puthash "c" 3 xx)
  xx)
;; #s(hash-table test equal data ("a" 1 "b" 2 "c" 3))

(gethash "c" xx)
;; 3

Example. Create Hashtable, with Symbol Keys

(progn
  (setq xx (make-hash-table :test 'eq))
  (puthash :a 1 xx)
  (puthash :b 2 xx)
  (puthash :c 3 xx)
  xx)
;; #s(hash-table test eq data (:a 1 :b 2 :c 3))

(gethash :c xx)
;; 3

Elisp: Keyword Symbol (Colon Prefix)

Example. Create Hashtable, with Integer Keys

(progn
  (setq xx (make-hash-table :test 'eq))
  (puthash 1 30 xx)
  (puthash 2 71 xx)
  (puthash 3 49 xx)
  xx)
;; #s(hash-table test eq data (1 30 2 71 3 49))

(gethash 3 xx)
;; 49

Example. Create Hashtable, with Float Number Keys

(progn
  (setq xx (make-hash-table :test 'eql))
  (puthash 1.067 1 xx)
  (puthash 2.948 2 xx)
  (puthash 3.019 3 xx)
  xx)
;; #s(hash-table data (1.067 1 2.948 2 3.019 3))

(gethash 2.948 xx)
;; 2

Literal Expression for Hashtable

You can create a hash table by a literal expression, like this:

(setq xx
      #s(hash-table
         size 30
         test equal
         data (
               "aa" 3
               "bb" 9
               "cc" 5 )))

(gethash "aa" xx )
;; 3

Length (Count of Entries)

hash-table-count

(hash-table-count xhash)

Add Entry

puthash

(puthash KEY VALUE TABLE)

(setq xx (make-hash-table :test 'equal))

(puthash "aa" 9 xx)
;; 9

Remove Entry

remhash

(remhash KEY TABLE)

Remove KEY from TABLE.

(setq xx (make-hash-table :test 'equal))
;; #s(hash-table test equal)

(puthash "aa" 9 xx)
;; 9

(puthash "bb" 10 xx)
;; 10

(remhash "aa" xx)
;; nil

xx
;; #s(hash-table test equal data ("bb" 10))

Check Key Exist

see gethash

Get Key's Value

gethash

(gethash key table)
(gethash key table default)

If a key exist, return key's value. Else, return nil or default

(let ((xx (make-hash-table :test 'equal)))
  (puthash "aa" 9 xx)
  (gethash "aa" xx))
;; 9

(let ((xx (make-hash-table :test 'equal)))
  (puthash "aa" 9 xx)
  (gethash "bb" xx))
;; nil

(let ((xx (make-hash-table :test 'equal)))
  (puthash "aa" 9 xx)
  (gethash "bb" xx 10))
;; 10

Remove All Entries

clrhash

(clrhash xhash)

Apply a Function to All Entries

maphash

(maphash f hashtable)

Apply a function to all entries in a hash table. The function f must take 2 arguments, key and value.

(setq xx (make-hash-table :test 'equal))
(puthash "aa" 19 xx)
(puthash "bb" 20 xx)
(puthash "dd" 17 xx)
(puthash "cc" 21 xx)

(maphash
   (lambda (k v)
     (princ (format "%s , %s" k v))
     (princ "\n"))
   xx
   )

Get All Keys

hash-table-keys

(hash-table-keys xhash)

Return a list of keys.

(require 'subr-x)

New in Emacs 24.4 (date 2014-10)

;; get all keys from a hash table

(setq xx
      #s(hash-table
         size 30
         test equal
         data (
               "aa" 3
               "bb" 9
               "cc" 5 )))

;; get all keys
(require 'subr-x)
(hash-table-keys xx) ; ("aa" "bb" "cc")

Get All Values

hash-table-values

(hash-table-values xhash)

Return a list of values.