1 History and development

1.1 Origins and motivation

Before Quicklisp, managing Common Lisp libraries was a cumbersome process. Developers had to manually download tarballs, track dependencies, and configure ASDF (Another System Definition Facility) paths. Zach Beane, a longtime Common Lisp enthusiast, recognized the need for a centralized, automated system akin to package managers in other languages (e.g., Ruby’s Rubygems or Python’s pip). Quicklisp was designed to eliminate manual dependency resolution, provide a single reliable source for libraries, and work across all major Lisp implementations without requiring system‑level privileges.

1.2 Early releases and community adoption

The first public release of Quicklisp occurred in 2010. It quickly gained traction thanks to its simple installation process (a single load command) and the inclusion of a curated library set. The Common Lisp community, which had long struggled with fragmentation, embraced Quicklisp as a unifying tool. By 2012, most popular open‑source Lisp libraries were available through the repository, and adoption became near‑universal among hobbyists and professionals alike.

1.3 Version history and significant milestones

  • 2010 (v0.1): Initial release with a small set of libraries and basic client commands.
  • 2011 (v0.5): Introduction of ql:quickload as the primary loading function; improved dependency resolution.
  • 2013 (v1.0): Stable release featuring a dedicated distribution server, automated monthly updates, and support for pinned versions.
  • 2015 (v1.5): Added the ql:bundle system for offline usage and reproducible builds.
  • 2018 (v1.7): Enhanced support for multiple Lisp implementations and better integration with ASDF 3.
  • 2020 (v2.0): Major overhaul of the distribution infrastructure, introduction of the quicklisp-beta channel for testing new libraries.
  • 2023 (v2.5): Continued maintenance with focus on compatibility with modern Lisp compilers and security updates.

2 Installation

2.1 Prerequisites (Common Lisp implementation)

Quicklisp requires a working Common Lisp implementation installed on the system. Supported implementations include SBCL (Steel Bank Common Lisp), CCL (Clozure Common Lisp), CLISP, ECL (Embeddable Common Lisp), Allegro CL, LispWorks, and others. No additional system tools (like git or curl) are strictly necessary, as the client downloads files via the Lisp implementation’s built‑in HTTP facilities.

2.2 Downloading and loading Quicklisp

The recommended method is to download the Quicklisp installer from the official website (www.quicklisp.org). Users open a Lisp REPL and evaluate:

(load "https://beta.quicklisp.org/quicklisp.lisp")

The installer script then guides the user through the process. Alternatively, the file can be saved locally and loaded from disk.

2.3 Initial setup and configuration

After loading the installer, the user runs:

(quicklisp-quickstart:install)

This command downloads the Quicklisp client, sets up the default directory (~/quicklisp/ on Unix systems), and creates the necessary configuration files.

2.3.1 Adding Quicklisp to the Lisp startup file

To make Quicklisp available automatically in every new Lisp session, the installer offers to add code to the user’s initialization file (e.g., ~/.sbclrc for SBCL, ~/.ccl-init.lisp for CCL, or the appropriate file for the implementation). The typical entry is:

(ql:quickload "quicklisp")

This ensures that ql: commands are available without manual loading.

2.4 Verifying installation

Users can verify a successful installation by evaluating:

(ql:client-version)

If Quicklisp is correctly set up, this returns a version string (e.g., "2023-03-03"). Additionally, running (ql:system-list) will display the list of available systems from the distribution.

3 Basic usage

3.1 Searching for libraries

Quicklisp provides the ql:system-apropos function to search for libraries by name or description. For example:

(ql:system-apropos "web")

returns a list of all registered systems whose names or descriptions contain “web”. The output includes each system’s name, short description, and version.

3.2 Installing a system

Installing a library (called a “system” in Lisp parlance) is done with ql:quickload. This command downloads the system and all its dependencies, compiling them as needed. Example:

(ql:quickload "cl-json")

The first invocation may take a few minutes, as the distribution snapshot is fetched and cached. Subsequent loads of the same system are immediate.

3.3 Loading a system into the current Lisp image

ql:quickload also makes the system’s exported symbols available in the current Lisp image. After loading, the user can immediately use the library’s functions. For instance, after loading cl-json, one can call (json:encode-json ...) without additional steps.

3.4 Updating the Quicklisp distribution

The distribution snapshot (which contains the list of all available systems and their versions) is updated monthly by the Quicklisp maintainer. Users can synchronize their local copy with:

(ql:update-dist "quicklisp")

This downloads the latest metadata but does not automatically upgrade already‑installed libraries. To upgrade a specific system, one can use ql:quickload again, which will fetch the newest version available in the updated distribution.

3.5 Removing or updating libraries

Quicklisp does not provide a dedicated “uninstall” command. Removing a system simply means not loading it; its source files remain in the local cache. For updating, users either run ql:update-dist followed by re‑loading the system, or use ql:quickload with a version pin (see Section 5.4). To manually delete cached files, users can remove the system’s directory from ~/quicklisp/dists/quicklisp/software/.

4 Repository and distribution

4.1 The Quicklisp distribution server

Quicklisp’s central repository is hosted on a dedicated server maintained by Zach Beane. The server stores metadata files (listing system names, versions, dependencies, and download URLs) as well as the actual library archives (as tarballs). All communication uses HTTPS. The client fetches metadata and software only when needed; after the initial download, local caching avoids redundant transfers.

4.2 Release cycles and snapshot versions

The distribution is updated approximately once per month. Each update is a “snapshot” – a consistent set of library versions that have been tested for compatibility. Snapshot releases are numbered by date (e.g., 2024-02-01). Users are encouraged to stay on the latest snapshot to receive bug fixes and new libraries, but they may also pin a specific snapshot for reproducibility (see Section 5.4).

4.3 Submitting a library to Quicklisp

Library authors can request inclusion by following the submission guidelines on the Quicklisp website.

4.3.1 Requirements for inclusion

To be accepted, a library must:

  • Be open‑source under an OSI‑approved license.
  • Use ASDF for system definition.
  • Have no external dependencies that are not themselves available in Quicklisp.
  • Pass basic automated tests (e.g., compilation on the latest SBCL).
  • Provide a reasonable set of documentation (at minimum, a README with installation and usage instructions).

4.3.2 The review and integration process

Submissions are reviewed by Zach Beane or designated community members. The review checks code quality, dependency correctness, and license compatibility. Once approved, the library is added to the next monthly snapshot. Authors are responsible for keeping their libraries compatible with the latest snapshot; if a library breaks, it may be temporarily removed until fixed.

5 Advanced features

5.1 Managing multiple Lisp implementations

Quicklisp works with multiple Lisp implementations installed on the same machine. Each implementation maintains its own cache under ~/quicklisp/impl/<impl-name>. When a user runs ql:quickload in SBCL, the dependencies are compiled to SBCL’s native format; the same system loaded later in CCL will be compiled anew. Quicklisp automatically distinguishes between implementations, so users can switch between REPLs without conflict.

5.2 Using Quicklisp with ASDF (Another System Definition Facility)

Quicklisp integrates seamlessly with ASDF. When ql:quickload is called, it first ensures the distribution metadata is up to date, then uses ASDF to compile and load the requested system. The ql client registers its own ASDF source registry pointing to the local cached libraries. Users can also mix Quicklisp systems with manually installed ones by managing ASDF source‑registry paths.

5.3 Custom local-projects directories

Developers may want Quicklisp to also search a local directory for in‑development libraries. This is done by setting the ql:*local-project-directories* variable. For example:

(push "/home/user/my-lisp-projects/" ql:*local-project-directories*)

After adding the directory, ql:quickload will find systems there as well, allowing seamless development alongside the curated public libraries.

5.4 Pinning library versions for reproducibility

For projects that require deterministic builds, Quicklisp supports pinning to a specific snapshot date. Users can set:

(ql:quickload :my-system :version "2023-06-01")

This forces ql:quickload to use the versions from that snapshot. Additionally, the ql:bundle system can create a self‑contained archive of all dependencies for a given project, enabling offline deployment without reliance on the server.

5.5 Offline usage and caching

Once a system and its dependencies have been loaded, they remain cached in ~/quicklisp/software/. Users can work offline as long as they do not need to download new libraries. ql:bundle further facilitates offline builds by packaging all required systems into a single directory tree that can be copied to another machine.

6 Troubleshooting and common issues

6.1 Network connectivity problems

If ql:quickload fails with timeouts or connection errors, the most common cause is a firewall or proxy. Users behind HTTP proxies must configure the Lisp implementation to use the proxy (e.g., setting http-proxy in SBCL). In restricted environments, manually downloading the distribution archive from the Quicklisp website and placing it in the local cache may help.

6.2 Dependency conflicts

Because Quicklisp’s distribution is a consistent snapshot, dependency conflicts (e.g., two libraries requiring incompatible versions of a third) are rare. When they occur, the user can either wait for the next snapshot (which may resolve the conflict) or manually override by using a local‑projects directory with a fixed version of the conflicting library.

6.3 Version mismatch errors

After updating the distribution, an error like “System X requires version Y of Z, but version W is loaded” typically indicates that the user has an older version of a system still in memory. The solution is to restart the Lisp image and reload the affected systems with ql:quickload. For persistent issues, one can clear the cache by deleting the relevant directory under ~/quicklisp/software/ and re‑downloading.

6.4 Quicklisp and SBCL, CCL, or other implementations

Some implementations have known quirks:

  • SBCL: Quicklisp works out of the box. Users may need to increase memory with --dynamic-space-size for large compilations.
  • CCL: The startup file location differs; ensure Quicklisp is added to ~/.ccl-init.lisp.
  • CLISP: Older versions of CLISP have limited HTTP functionality; using a local installer file is recommended.
  • ECL: Works but compilation times can be longer due to C generation.

In all cases, checking the implementation’s documentation and the Quicklisp website for specific gotchas is advisable.

7 Alternatives and complementary tools

7.1 Other Common Lisp package managers (e.g., clpm, Ultralisp)

  • clpm: A newer package manager that supports multiple repositories and version locking using a clpmfile. It focuses on reproducible builds and integration with CI systems.
  • Ultralisp: A community‑maintained distribution that includes libraries not yet in Quicklisp. It works as an additional “dist” that can be added to Quicklisp’s client via (ql:add-dist "ultralisp" "https://dist.ultralisp.org/"). Ultralisp updates much more frequently (sometimes daily) but may have less stability.

Both tools are designed to coexist with Quicklisp; users can switch between them as needed.

7.2 Integration with build systems (e.g., Quickproject, cl-project)

  • Quickproject: Automates creating new Lisp projects with a standard ASDF layout, and can optionally load Quicklisp in the generated system definition.
  • cl-project: A newer alternative that generates project skeletons with modern tooling, including integration with both Quicklisp and ASDF.

These tools reduce boilerplate when starting a new Common Lisp library or application.

8 See also

  • ASDF (Another System Definition Facility)
  • Common Lisp
  • SBCL (Steel Bank Common Lisp)
  • Ultralisp
  • clpm (Common Lisp Package Manager)

9 References and further reading

  • Beane, Zach. “Quicklisp: A Library Manager for Common Lisp.” *quicklisp.org*, 2010–2023.
  • Common Lisp Community. *Practical Common Lisp*. Sections on ASDF and Quicklisp.
  • “Quicklisp User Guide.” *quicklisp.org/help/*. Accessed 2024.
  • “clpm Documentation.” *clpm.dev*. Accessed 2024.
  • “Ultralisp Repository.” *ultralisp.org*. Accessed 2024.