You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Docjure makes reading and writing Office Excel spreadsheet documents
in Clojure easy.
Who is this for?
Docjure is aimed at making the basic use case of reading and writing
spreadsheets easy.
If you need advanced charting, pivot tables etc., the easiest way is
to build template spreadsheets with Excel and populate them with
Docjure.
If you want to manipulate advanced features programatically,
you are probably better off using the underlying Apache POI
spreadsheet library directly or looking for another tool.
Docjure has low churn. It is very stable library with a history going
back to 2009 (open-sourced in 2010).
Usage
The complete documentation is available on cljdoc.
;; Load a spreadsheet and read the first two columns from the ;; price list sheet: (->> (load-workbook"spreadsheet.xlsx") (select-sheet"Price List") (select-columns {:A:name, :B:price}))
If you want to read a single cell value, you can use the select-cell function which
takes an Excel-style cell reference (A2) and returns the cell. In order to get the
actual value, use read-cell
This example loads a workbook from a named file. In the case of running
in the application server, the file typically resides in the resources directory,
and it's not on the caller's path. To cover this scenario, we provide
the function 'load-workbook-from-resource' that takes a named resource
as the parameter. After a minor modification, the same example will look like:
The function 'load-workbook' is a multimethod, and the first example takes
a file name as a parameter. The overloaded version of 'load-workbook'
takes an InputStream. This may be useful when uploading a workbook to the server
over HTTP connection as multipart form data. In this case, the web framework
passes a byte buffer, and the example should be modified as (note that you have
to use 'with-open' to ensure that the stream will be closed):
This example creates a spreadsheet with a single sheet named "Price List".
It has three rows. We apply a style of yellow background colour and bold font
to the top header row, then save the spreadsheet.
(use 'dk.ative.docjure.spreadsheet)
;; Create a spreadsheet and save it (let [wb (create-workbook"Price List" [["Name""Price"] ["Foo Widget"100] ["Bar Widget"200]]) sheet (select-sheet"Price List" wb) header-row (first (row-seq sheet))] (set-row-style! header-row (create-cell-style! wb {:background:yellow, :font {:boldtrue}})) (save-workbook!"spreadsheet.xlsx" wb))
Example: Create a workbook with multiple sheets
This example creates a spreadsheet with multiple sheets. Simply add more
sheet-name and data pairs. To create a sheet with no data, pass nil as
the data argument.
(use 'dk.ative.docjure.spreadsheet)
;; Create a spreadsheet and save it (let [wb (create-workbook"Squares" [["N""N^2"] [11] [24] [39]] "Cubes" [["N""N^3"] [11] [28] [327]])] (save-workbook!"exponents.xlsx" wb))
Example: Use Excel Formulas in Clojure
Docjure allows you not only to evaluate a formula cell in a speadsheet, it also
provides a way of exposing a formula in a cell as a Clojure function using the
cell-fn function.
(use 'dk.ative.docjure.spreadsheet) ;; Load a speadsheet and take the first sheet, construct a function from cell A2, taking ;; A1 as input. (def formula-from-a2 (cell-fn "A2" (first (sheet-seq (load-workbook "spreadsheet.xlsx"))) "A1"))
;; Returns value of cell A2, as if value in cell A1 were 1.0 (formula-from-a2 1.0)
Example: Handling Error Cells
If the spreadsheet being read contains cells with errors the default
behaviour of the library is to return a keyword representing the
error as the cell value.
It's worth understanding a bit about the underlying structure of a spreadsheet before you
start iterating over the contents.
Spreadsheets are designed to be sparse - not all rows in the spreadsheet must physically exist,
and not all cells in a row must physically exist. This is how you can create data at ZZ:65535 without
using huge amounts of storage.
Thus each cell can be in 3 states - with data, blank, or nonexistent (null). There's a special type CellType.BLANK for blank cells, but missing cells are just returned as nil.
Similarly rows can exist with cells, or exist but be empty, or they can not exist at all.
Prior to Docjure 1.11 the iteration functions wrapped the underlying Apache POI iterators, which skipped over missing data - this could cause surprising behaviour, especially when there were missing cells inside tabular data.
Since Docjure 1.11 iteration now returns nil values for missing rows and cells - this is a breaking change - any code that calls row-seq or cell-seq now needs to deal with possible nil values.
Iterating over rows
You can iterate over all the rows in a worksheet with row-seq:
This will return a sequence of org.apache.poi.usermodel.Row objects, or nil for any missing rows. You can use (remove nil? (row-seq ...) ) if you are happy to ignore missing rows, but then be aware the nth result in the sequence might not match the nth row in the spreadsheet.
Iterating over cells
You can iterate over all the cells in a row with cell-seq - this returns a sequence of org.apache.poi.usermodel.Cell objects, or nil for missing cells. Note that (read-cell nil) returns nil so it's safe to apply read-cell to the results of cell-seq
You can adjust the column widths to they fit the contents.
This makes generated workbooks look nicer.
For example, to auto-size all the columns in all the sheets
in a workbook, use this:
;; wb is a workbook (dorun (for [sheet (sheet-seq wb)] (auto-size-all-columns! sheet)))
To apply auto-width to individual columns in a sheet, use the
auto-size-column! function.
Automatically get the Docjure jar from Clojars
The Docjure jar is distributed on
Clojars. Here you can find both
release builds and snapshot builds of pre-release versions.
Using Leiningen
If you are using the Leiningen build tool just add this line to the
:dependencies list in project.clj to use it:
[dk.ative/docjure "1.21.0"]
Example project.clj for using Docjure 1.21.0
(defprojectsome.cool/project"1.0.0-SNAPSHOT" :description"Spreadsheet magic using Docjure" :dependencies [[org.clojure/clojure "1.12.0"] [dk.ative/docjure "1.21.0"]])
Using deps.edn with the Clojure CLI
To add Docjure to a project using the Clojure CLI tools, add the dependency to your deps.edn file:
{:deps {dk.ative/docjure {:mvn/version"1.21.0"}}}
Installation for Contributors
You need to install the Leiningen build tool to build the library.
You can get it here: Leiningen
The library uses the Apache POI library which will be downloaded by
the "lein deps" command.
Then build the library:
lein deps lein compile lein test
To run the tests on all supported Clojure versions use:
lein all test
To check for security issues use:
lein nvd check
To check for new versions of dependencies:
lein ancient
To run the static analysis of the code:
lein clj-kondo
Releasing to Clojars
When releasing a version to Clojars you must provide your user-name. The password is a deployment token, not your normal password. You can generate this by logging into Clojars. These tokens have an expiration date so if it does not work, log in a check if you need a new token.
lein deploy clojars
You also need a GPG key to sign the releases.
These also expire, and must be periodically renewed. You can check your keys and their status like this:
gpg --list-keys
See also lein help deploy and lein help gpg.
Remember to tag releases in git. You can list the tags with git tag -n and tag with git tag -a TAGNAME -m 'Tag comment'.
Build Status
License
Copyright (c) 2009-2025 Martin Jul
Docjure is licensed under the MIT License. See the LICENSE file for
the license terms.
Docjure uses the Apache POI library, which is licensed under the
Apache License v2.0.
A special thank you also goes out to people that did not contribute code
but shared their ideas, reported security issues or bugs and otherwise
inspired the continuing work on the project.