Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

cl4py - Common Lisp for Python

The library cl4py (pronounce as clappy) allows Python programs to call Common Lisp libraries. Its official mascot is the cl4py-bird:



You are a Python programmer, but you want access to some of the powerful features of Lisp, for example to compile code at run time? Or you want to use some awesome Lisp libraries? Or you are a Lisp programmer and want to show your work to your Python friends. In all these cases, cl4py is here to help you.


You can start any number of Lisp subprocesses within Python, like this:

>>> import cl4py
>>> lisp = cl4py.Lisp()

Of course, this requires you have some Lisp installed. If not, use something like apt install sbcl, pacman -S sbcl or brew install sbcl to correct this deficiency. Once you have a running Lisp process, you can execute Lisp code on it:

>>> lisp.eval( ('+', 2, 3) )

>>> add = lisp.function('+')
>>> add(1, 2, 3, 4)

>>> div = lisp.function('/')
>>> div(2, 4)
Fraction(1, 2)

# You can look up variable values using Symbol structures
>>> lisp.eval(cl4py.Symbol('*PRINT-BASE*', "COMMON-LISP"))

Some Lisp data structures have no direct equivalent in Python, most notably, cons cells. The cl4py module provides a suitable Cons class and converts List conses to instances of cl4py.Cons.

>>> lisp.eval( ('CONS', 1, 2) )
Cons(1, 2)

>>> lst = lisp.eval( ('CONS', 1, ('CONS', 2, () )) )
List(1, 2)
>>> lst.cdr
List(2) # an abbreviation for Cons(2, ())

# cl4py Conses are iterable!
>>> list(lst)
[1, 2]
>>> sum(lst)

It soon becomes clumsy to look up individual Lisp functions by name. Instead, it is usually better to convert entire Lisp packages to Python modules, like this:

>>> cl = lisp.function('find-package')('CL')
>>> cl.oddp(5)

>>> cl.cons(5, None)

>>> cl.remove(5, [1, -5, 2, 7, 5, 9], key=cl.abs)
[1, 2, 7, 9]

# Common Lisp names with hyphens are translated into
# names with underscores
>>> cl.type_of("foo")
List(Symbol("SIMPLE-ARRAY", "COMMON-LISP"), Symbol("CHARACTER", "COMMON-LISP"), List(3))
# note that strings (including symbol names) are *not* translated
# in this way, so we have "COMMON-LISP", not "COMMON_LISP", and
# these names are case-flattened to upper case.

# Higher-order functions work, too!
>>> cl.mapcar(cl.constantly(4), (1, 2, 3))
List(4, 4, 4)

# Of course, circular objects of all kinds are supported.
>>> twos = cl.cons(2,2)
>>> twos.cdr = twos
>>> cl.mapcar(lisp.function('+'), (1, 2, 3, 4), twos)
List(3, 4, 5, 6)

Frequently Asked Problems

Why does my Lisp subprocess complain about Package QL does not exist.

By default, cl4py starts a Lisp subprocess with sbcl --script. This means, that the Lisp process will ignore any user initialization files, including the Quicklisp setup. However, we provide an extra option for installing and loading Quicklisp automatically: quicklisp=True

>>> lisp = cl4py.Lisp(quicklisp=True); cl = lisp.function('find-package')('CL')
>>> ql = cl.find_package('QL')
>>> ql.quickload('YOUR-SYSTEM')

Related Projects

  • burgled-batteries - A bridge between Python and Lisp. The goal is that Lisp programs can use Python libraries, which is in some sense the opposite of cl4py. Furthermore it relies on the less portable mechanism of FFI calls.
  • CLAUDE - An earlier attempt to access Lisp libraries from Python. The key difference is that cl4py does not run Lisp directly in the host process. This makes cl4py more portable, but complicates the exchange of data.
  • cl-python - A much heavier solution than cl4py --- let's simply implement Python in Lisp! An amazing project. However, cl-python cannot access foreign libraries, e.g., NumPy. And people are probably hesitant to migrate away from CPython.
  • Hy - Python, but with Lisp syntax. This project is certainly a great way to get started with Lisp. It allows you to study the advantages of Lisp's seemingly weird syntax, without leaving the comfortable Python ecosystem. Once you understand the advantages of Lisp, you will doubly appreciate cl4py for your projects.
  • py4cl - A library that allows Common Lisp code to access Python libraries. It is basically the inverse of cl4py.


Common Lisp for Python





No releases published


No packages published