Installing Ciao

Author(s): Jose F. Morales, Manuel Carro, Daniel Cabeza, Manuel Hermenegildo.

This describes the installation procedure for the Ciao Prolog system, including libraries and manuals:

  1. Check / install the requirements and dependencies.
  2. Begin the interactive network-based installation typing the following one-liner in an sh-compatible terminal:
    curl -sSfL | sh
This installs Ciao by default in ~/.ciaoroot/<ciao_version>.

Please report as issues any problems found during the installation process.

You can explore additional components at the bundle catalog (including links to documentation and source code repositories) and install them with the ciao get BUNDLENAME command (see also bundle management).

For customized installations or developer builds, please consult the manual installation from source instructions.

Requirements and dependencies

Ciao supports many operating systems, including:

  • Linux distributions
  • macOS
  • Windows (with WSL)
  • Android (with Termux).
Installing Emacs or Ciao support for VSCode is highly recommended: the Ciao distribution includes a very powerful application development environment which enables, e.g., syntax coloring, source code formatting, embedded top-level, source-level debugging, context-sensitive on-line help, generating documentation, etc., etc.

In any case, it is easy to use Ciao from a terminal and edit code with any editor of your choice. The top level includes some minimal editing facilities when rlwrap is available.

Installing dependencies for your operating system

Depending on the operating system and package management tool, you may need to install the following dependencies (using sudo or as administrator or root user):

  • Debian/Ubuntu:
    $ apt-get install build-essential
    $ apt-get install emacs # optional
    $ apt-get install rlwrap # optional
    $ apt-get install texlive texinfo imagemagick # optional
  • Debian/Ubuntu (additional for x86, 32-bits):
    $ apt-get install gcc-multilib libc6-i386 libc6-dev-i386 g++-multilib
  • Fedora:
    $ dnf install gcc make which kernel-headers kernel-devel
    $ dnf install emacs # optional
    $ dnf install rlwrap # optional
    $ dnf install texlive texinfo texinfo-tex ImageMagick # optional
  • Fedora (additional for x86, 32-bits):
    $ dnf install glibc-devel.i686 glibc-devel libstdc++-devel.i686
  • Arch Linux:
    $ pacman -Syu # optional, upgrade if needed
    $ pacman -S base-devel linux-headers
    $ pacman -S emacs # optional
    $ pacman -S rlwrap # optional
    $ pacman -S texlive-core texinfo imagemagick # optional
  • Arch Linux (additional for x86, 32-bits):
    $ pacman -S lib32-glibc lib32-libstdc++5
    Remember to enable multilib (
  • macOS:
    • Install command line tools for Xcode (from the App store)
    • Install emacs and ImageMagick (and texinfo if needed, but recent versions of macOS include it). A software management tool like homebrew or macports is recommended, e.g. (as root/sudo):
      $ brew install emacs-mac imagemagick
    • Install TexLive. If using homebrew we recommend installing the MacTeX distribution, available from:
    • Install the following packages:
      $ brew install rlwrap # optional
  • FreeBSD:
    • Install GCC or clang and the following packages:
      $ pkg install gmake
      $ pkg install emacs ImageMagick expat # optional
      $ pkg install rlwrap # optional
      $ pkg install texinfo texlive-full # optional
  • NetBSD:
    • Install GCC or clang and the following packages:
      $ pkgin install gmake
      $ pkgin install emacs ImageMagick expat # optional
      $ pkgin install rlwrap # optional
      $ pkgin install tex-texinfo texlive-collection-latex # optional
  • Windows (using Windows Subsystem or Linux):
    • Install WSL
    • Install some Linux distribution (e.g., Ubuntu) from the Windows Store.
    • Open a wsl terminal and install the dependencies for the selected distribution (see points above), e.g., Debian/Ubuntu.
  • Windows (native, experimental)
    • Install MSYS2 and the following packages:
      pacman --noconfirm -S mingw-w64-x86_64-gcc
  • Android (using the Termux Linux environment):
    • Install Termux
    • Install the following packages:
      $ pkg install clang make
      $ pkg install emacs # optional
      $ pkg install rlwrap # optional
The dependencies above typically include a relatively modern C compiler (GCC or clang), libraries, and build tools. The optional dependencies are:

  • emacs: required for emacs-based IDE (use emacs-nox if no graphical interface is needed)
  • ImageMagick: used image conversion in lpdoc (use ImageMagick-nox if no graphical interface is needed)
  • TeX: typesetting system used as backed to generate documentation in info and PDF formats.
  • rlwrap: readline wrapper utility that provides line edition from terminals.

Upgrading or uninstalling components

Bundles installed via ciao get must be uninstalled and removed explicitly. Currently, this needs to be done manually per bundle. Upgrading a bundle requires uninstallation followed by (re)installation.

E.g., uninstalling the development environment (if installed) requires:

ciao uninstall ciao_emacs; ciao rm ciao_emacs; ciao rm devenv

Upgrading or uninstalling Ciao

For full cleanup, first remove all installed bundles (see above).

Once all bundles have been removed, the core Ciao system can be uninstalled running ./ uninstall from the source directory; then, remove the directory.

If installed using curl, the system is installed in a per-version subdirectory under ~/.ciaoroot, i.e., ~/.ciaoroot/<ciao_version>. The development version is installed at ~/.ciaoroot/master. Proper uninstallation requires first executing ./ uninstall inside that directory and then removing the whole ~/.ciaoroot/<ciao_version> directory.

This can be automated with a script such as (e.g., for master):

( cd ~/.ciaoroot/master; ./ uninstall )
rm -rf ~/.ciaoroot/master
rmdir ~/.ciaoroot > /dev/null 2>&1 || true

Network-based installation options

The network installer is delivered as an HTTPs redirection to (which contains the latest version of the script). The bootstrap script recognizes that it is being called without sources automatically. Ciao can be installed from the network using a curl pipe from to sh in a terminal. This is probably the fastest/easiest way to install Ciao in binary or source form.


# Interactive
curl -sSfL | sh
# Minimal local installation with prebuilt binaries
curl -sSfL | sh -s -- --prebuilt-bin local-install
# Full environment
curl -sSfL | sh -s -- get devenv
# Show network installer help
curl -sSfL | sh -s -- --help

Manual installation from source

You can get the source code for the latest stable and development versions of Ciao by cloning the Ciao repository:
git clone
Installation of Ciao from source is driven by the script (ciao-boot.bat in Windows), which bootstraps and invokes the Ciao build system.

  1. Type ./ configure. This command will attempt to detect the configuration options for your system automatically and select reasonable defaults.

    Options can be configured interactively using ./ configure --interactive or passed explicitly as arguments from the command-line (see Customize your installation and ./ help for more information). In particular, make sure the location of the emacs executable is set correctly.

  2. Type ./ fetch devenv (for the full development environment, optional). This will fetch the source of other components required for the development environment. This step is not needed when compiling Ciao from the monorepository.
  3. Type ./ build. This will build executables, compile libraries, and generate the documentation.
  4. Type ./ install. This will install everything in the specified directories.
Alternatively, provides shorthands to perform configure, build, and install in a single command:

  1. Type ./ local-install. This will do a user-local installation (that will be accessible just for your user).
  2. Type ./ global-install. This will do a system-wide installation (e.g., as administrator or root user).
  3. Type ./ get devenv to fetch, configure, and install the full environment (devenv bundle).
The system will include appropriate code at the end of your startup scripts. This will make the documentation and executables accessible, make sure the correct mode is set when opening Ciao source files in emacs, etc.

Cleaning up the source directory

After a global installation, the source directory can be cleaned up using ./ realclean, leaves the distribution is its original form, throwing away any intermediate files (as well as any unneeded files left behind by the Ciao developers), while still allowing recompilation.


Type ./ uninstall in the top directory to uninstall the system. To ensure that this process works, configuration should have not changed since installation, so that the same directories are cleaned.

Customize your installation

You can configure and customize your Ciao installation with the command:

./ configure
By default, it will perform a default configuration, where the system will be configured to run from the sources directly, and configured in the user's home directory (recommended for Ciao developers or users without admin rights).

The option --instype=global will prepare Ciao to be installed as the system administrator (root) in a standard directory available for all users in the machine (e.g., /usr/local).

For 32-bit builds in 64-bit architectures use the --core:m32=yes configuration flag.

In case you want to install elsewhere, or change any of the installation options, you can use a customized configuration procedure (see ./ help for more information). The meaning of some important options is as follows:

  • --prefix: prefix for the default values of installation directories (<prefix>/bin, <prefix>/lib, etc).
  • --bindir: directory where the Ciao commands will be installed. For example, if --bindir is set to /usr/local/bin, then the Ciao compiler (ciaoc) will be stored at /usr/local/bin/ciaoc. Actually, it will be a link to ciaoc-VersionNumber. This applies also to other executables below and is done so that several versions of Ciao can coexist on the same machine. Note that the version installed latest will be the one started by default when typing ciao, ciaoc, etc.
  • The Ciao installation procedure will create a new subdirectory ciao/<vers> denoted INSTALL_CIAOROOT below --prefix. The <vers> directory indicate the Ciao system version. It allows having several Ciao versions installed simultaneously.
  • --mandir: directory where the manuals in man format will be installed.
  • --infodir: directory where the manuals in info format will be installed.

Once configured, the ./ build command and ./ install command will build and install Ciao, respectively, using the selected configuration options. This will:

  • Install the executables of the Ciao program development tools (i.e., the general driver/top-level ciao, the standalone compiler ciaoc, the script interpreter ciao-shell, miscellaneous utilities, etc.) in the selected binary directory. In order to use these tools, make sure that the PATH environment variable contains such path.
  • Install the Ciao libraries under INSTALL_CIAOROOT (these will be automatically found).
  • Install the Ciao manuals in several formats (such as GNU info, html, pdf, etc.) under INSTALL_CIAOROOT and other documentation-specific paths. In order for these manuals to be found when typing M-x info within emacs, or by the standalone info and man commands, the MANPATH and INFOPATH environment variables of users both need to contain the path specified at --mandir and --infodir. Documentation in other formats can be accesed with the ciao doc command.
  • Install under INSTALL_CIAOROOT the Ciao interface with GNU emacs (which provides an interactive interface to the Ciao program development tools, as well as some other auxiliary files).
Finally, the installation will modify the user startup files automatically by default to set up user environments. If you disable this option in the configuration or you wish to switch between different installations, it would be necessary to modify the startup files manually.

The installation process generates a ciao-env command to update the environments for sh-like and cshlike shells. It also generates a INSTALL_CIAOROOT/ciao-mode-init (for emacs) with appropriate definitions which will take care of all needed environment variable definitions and emacs mode setup.

  • For users a csh-compatible shell (csh, tcsh, ...), add to ~/.cshrc:
    if ( -x <prefix>/bin/ciao-env ) then
       eval `<prefix>/bin/ciao-env --csh`
  • For users of an sh-compatible shell (sh, bash, ...), the installer will add to ~/.bashrc the next lines:
    if [ -x <prefix>/bin/ciao-env ]; then
       eval "$(<prefix>/bin/ciao-env --sh)"
  • For users of an zsh shell, the same lines will be added to ~/.zshrc.

    This will set up things so that the Ciao executables are found and you can access the Ciao system manuals using the info command. Note that, depending on your shell, you may have to log out and back in for the changes to take effect.

  • Also, if you use emacs (highly recommended) the install will add the next line to your ~/.emacs file:
    (load-file "INSTALL_CIAOROOT/ciao-site-file.el")
    (if (file-exists-p "INSTALL_CIAOROOT/ciao-site-file.el")
      (load-file "INSTALL_CIAOROOT/ciao-site-file.el")
If you are installing Ciao globally in a multi-user machine, make sure that you instruct all users that to do the same. If you are the system administrator, the previous steps can be done once and for all, and globally for all users by including the lines above in the central startup scripts (e.g., in Linux /etc/bashrc, /etc/csh.login, /etc/csh.cshrc, /etc/skel, /usr/share/emacs/.../lisp/, etc.).

Checking for correct installation

If you have any problems you may want to check Troubleshooting. Otherwise, if everything has gone well, several applications and tools should be available to a normal user. Try the following while logged in as a normal user (important in order to check that permissions are set up correctly):

  • Typing ciao (or ciaosh) should start the typical Prolog-style top-level shell.

  • In the top-level shell, Ciao library modules should load correctly. Type for example use_module(library(dec10_io)) --you should get back a prompt with no errors reported.

  • To exit the top level shell, type halt. as usual, or ^D.

  • Typing ciaoc should produce the help message from the Ciao standalone compiler.

  • Typing ciao-shell should produce a message saying that no code was found. This is a Ciao application which can be used to write scripts written in Ciao, i.e., files which do not need any explicit compilation to be run.

Also, the following documentation-related actions should work:

  • If the info program is installed, typing info should produce a list of manuals which should include Ciao manual(s) in a separate area (you may need to log out and back in so that your shell variables are reinitialized for this to work).

  • Typing ciao doc alldocs should open a series of Ciao-related manuals in a WWW browser.

  • Typing man ciao should produce a man page with some very basic general information on Ciao (and pointing to the on-line manuals).

  • The documentation directory should contain the manual also in the other formats such as pdf.

Finally, if emacs is installed, after starting it (typing emacs) the following should work:

  • Typing ^H i (or in the menus Help->Manuals->Browse Manuals with Info) should open a list of manuals in info format in which the Ciao manual(s) should appear.

  • When opening a Ciao file, i.e., a file with .pl or .pls ending, using ^X^Ffilename (or using the menus) the code should appear highlighted according to syntax (e.g., comments in red), and Ciao/Prolog menus should appear in the menu bar on top of the emacs window.

  • Loading the file using the Ciao/Prolog menu (or typing ^C l) should start in another emacs buffer the Ciao toplevel shell and load the file. You should now be able to switch the the toplevel shell and make queries from within emacs.

Note: when using emacs it is very convenient to swap the locations of the (normally not very useful) Caps Lock key and the (very useful in emacs) Ctrl key on the keyboard. How to do this is explained in the emacs frequently asked questions FAQs (see the emacs download instructions for their location).

Environment variables used by Ciao executables

The executables generated by the Ciao compiler (including the ciao development tools themselves) locate automatically where the Ciao engine and libraries have been installed, since those paths are stored as defaults in the engine and compiler at installation time. Thus, there is no need for setting any environment variables in order to run Ciao executables (on a single architecture -- see Multiarchitecture installation for running on multiple architectures).

However, the default paths can be overridden by using the environment variable CIAOROOT, which tell the Ciao executables where to look for engines and system libraries.

Multiarchitecture installation

In order to perform a multi-architecture installation, it is possible to repeat successively the build and installation process for several architectures from different machines sharing part of their filesystem.

The Ciao build and installation process maintains separate name spaces for platform- and architecture-dependant binaries (like the engine binary, or .so or .dll gluecode files for the foreign interface). Portable Ciao applications (i.e., except self-contained standalone executables) can run on several machines with different architectures without any need for recompiling, provided the Ciao engine and libraries are correctly installed.