Read Excel Files in Common Lisp

A new Lisp package I wrote cl-excel

What if reading Excel files in Common Lisp was as easy as reading CSV in Python? What if your spreadsheets just turned into usable Lisp data structures, ready for analysis, transformation, or web export? That was the idea behind cl-excel

Let me show you how it works and how it plays beautifully with cl-tibble and cl-tidyr — because spreadsheets are often messy, and Lisp deserves better tools to deal with them.

Introducing cl-excel: A Simple Excel I/O Library for Common Lisp

The goal of cl-excel is to make reading and writing data tables to/from Excel files easy in plain Common Lisp - no dependencies to other languages.

Install it

Optional: Install via Ultralisp (a fast Quicklisp-compatible distro)

If you want to get cl-excel without cloning into local-projects, using Ultralisp is the most modern and convenient workflow.

Ultralisp is a Quicklisp‑compatible Common Lisp distribution that updates very frequently — which means the latest version of cl-excel (or any related libraries) becomes downloadable within minutes rather than waiting for a monthly Quicklisp release. 

Here’s how you use it:

1. Tell Lisp about the Ultralisp distribution

;; in your Lisp REPL:
(ql-dist:install-dist "http://dist.ultralisp.org/"
                      :prompt nil)

This registers the Ultralisp “dist” so ql:quickload can see packages from Ultralisp as well as Quicklisp. 

That’s it! From here on you can use cl-excel (and any other library available through Ultralisp) without worrying about local-projects or manual cloning.

2. Load your package

;; now you can load cl-excel just like any other ASDF system:
(ql:quickload :cl-excel)

Manual Setup When Using Only Quicklisp

If you don't want to install Ultralisp, you have to manually go to the local-projects folder of your Quicklisp, usually ~/quicklisp/local-projects/

or if you are using Roswell, this will be ~/.roswell/local-projects/.

You have then to manually git clone the packages:

git clone https://github.com/gwangjinkim/cl-excel ~/quicklisp/local-projects/cl-excel

git clone https://github.com/gwangjinkim/cl-tibble ~/quicklisp/local-projects/cl-tibble
git clone https://github.com/gwangjinkim/cl-tidyr ~/quicklisp/local-projects/cl-tidyr

Then, after:

(ql:quickload :cl-excel)

(ql:quickload :cl-tibble)
(ql:quickload :cl-tidyr)
(ql:quickload :cl-depylr)

You’re ready.

Step-by-Step: Read Your First Excel Sheet

Say you have a file called example.xlsx with a sheet that looks like this:

Let’s read it:

(cl-excel:read-xlsx "example.xlsx")

This returns a list of sheets, where each sheet is a 2D list of rows, and each row is a list of cells.

You get something like:

((("Name" "Age" "Country")
  ("Alice" "33" "Germany")
  ("Bob"   "27" "USA")
  ("Carol" "45" "UK")))

Great, right? But we can do better. Let’s pipe this into cl-tibble.

Turn It Into a Tibble

(defparameter *table*
  (cl-tibble:from-rows
   (cdr (first (cl-excel:read-xlsx "example.xlsx")))
   :columns (first (first (cl-excel:read-xlsx "example.xlsx")))))

What you get is a proper tibble object, similar to R’s tidyverse or Python’s pandas dataframe. You can pretty-print it, subset it, transform it. It even has column names.

CL-TIBBLE> *table*
#<TIBBLE 3x3
  NAME     AGE  COUNTRY
--------  ---  --------
"Alice"   "33" "Germany"
"Bob"     "27" "USA"
"Carol"   "45" "UK">

Want to filter all rows where age > 30? No problem:

(cl-tidyr:filter *table*
  (lambda (row)
    (> (parse-integer (getf row :age)) 30)))

Why This Matters

The trio cl-excel, cl-tibble, and cl-tidyr gives you a full mini data science stack in Common Lisp:

• cl-excel: reads Excel files into clean Lisp data
• cl-tibble: turns them into accessible tables with names and metadata
• cl-tidyr: lets you filter, mutate, and reshape

You don’t need to fight raw lists, nor reinvent CSV readers. Just load the file, turn it into a tibble, and use your Lisp REPL to do the analysis interactively.

I would be happy to hear from you - when you tried the new package and get real-world jobs done!

Pull requests and issues welcome!

Check it out here:

https://github.com/gwangjinkim/cl-excel

And don’t forget to star the repo if you find it useful.

Happy hacking!