The cabal-install package
See the Cabal web site for more information.
cabal-install package provides a command line tool named
It uses the Cabal library and provides a user interface to the
Cabal/Hackage build automation and package management system. It can
build and install both local and remote packages, including
cabal command-line tool
cabal-install package requires a number of other packages, most of
which come with a standard GHC installation. It requires the network
package, which is sometimes packaged separately by Linux distributions;
for example, on Debian or Ubuntu, it is located in the
Note that on some Unix systems you may need to install an additional zlib development package using your system package manager; for example, on Debian or Ubuntu, it is located in the "zlib1g-dev" package; on Fedora, it is located in the "zlib-devel" package. It is required because the Haskell zlib package uses the system zlib C library and header files.
cabal-install package is now part of the Haskell Platform, so you
do not usually need to install it separately. However, if you are
starting from a minimal GHC installation, you need to install
cabal-install manually. Since it is an ordinary Cabal package,
cabal-install can be built the standard way; to facilitate this, the
process has been partially automated. It is described below.
Quick start on Unix-like systems
As a convenience for users on Unix-like systems, there is a
bootstrap.sh script that will download and install each of
cabal-install's dependencies in turn.
It will download and install the dependencies. The script will install the
library packages (vanilla, profiling and shared) into
$HOME/.cabal/ and the
cabal program into
$HOME/.cabal/bin/. If you don't want to install profiling
and shared versions of the libraries, use
$ EXTRA_CONFIGURE_OPTS="" ./bootstrap.sh
You then have the choice either to place
$HOME/.cabal/bin on your
$PATH or move the
cabal program to somewhere on your
you can get the latest list of packages by running:
$ cabal update
This will also create a default configuration file, if it does not
already exist, at
cabal will install programs to
$HOME/.cabal/bin. If you
do not want to add this directory to your
$PATH, you can change
the setting in the config file; for example, you could use the
Quick start on Windows systems
For Windows users, a precompiled program (cabal.exe) is provided.
Download and put it somewhere on your
%PATH% (for example,
Next, you can get the latest list of packages by running:
$ cabal update
This will also create a default configuration file (if it does not
already exist) at
C:\Documents and Settings\%USERNAME%\Application Data\cabal\config.
There are two sets of commands: commands for working with a local project build tree and those for working with packages distributed from Hackage.
For the list of the full set of commands and flags for each command, run:
$ cabal help
Commands for developers for local build trees
The commands for local project build trees are almost the same as the
runghc Setup command-line interface you may already be familiar with.
In particular, it has the following commands:
install command is somewhat different; it is an all-in-one
operation. If you run
cabal install in your build tree, it will
configure, build, and install. It takes all the flags that
takes such as
cabal will download and install any dependencies that are
not already installed. It can also rebuild packages to ensure a
consistent set of dependencies.
Commands for released Hackage packages
$ cabal update
This command gets the latest list of packages from the Hackage server. On occasion, this command must be run manually--for instance, if you want to install a newly released package.
$ cabal install xmonad
This command installs one or more named packages, and all their
dependencies, from Hackage. By default, it installs the latest available
version; however, you may specify exact versions or version ranges. For
cabal install alex-2.2 or
cabal install parsec < 3.
$ cabal list xml
This does a search of the installed and available packages. It does a case-insensitive substring match on the package name.
220.127.116.11 Mikhail Glushenkov <email@example.com> August 2017
* Removed the '--root-cmd' parameter of the 'install' command
* Deprecated 'cabal install --global' (#3356).
* Changed 'cabal upload' to upload a package candidate by default
(#3419). Same applies to uploading documentation.
* Added a new 'cabal upload' flag '--publish' for publishing a
package on Hackage instead of uploading a candidate (#3419).
* Added optional solver output visualisation support via the
tracetree package. Mainly intended for debugging (#3410).
* Removed the '--check' option from 'cabal upload'
(#1823). It was replaced by package candidates.
* Fixed various behaviour differences between network transports
* The bootstrap script now works correctly when run from a Git
* Removed the top-down solver (#3598).
* The '-v/--verbosity' option no longer affects GHC verbosity
(except in the case of '-v0'). Use '--ghc-options=-v' to enable
verbose GHC output (#3540, #3671).
* Changed the default logfile template from
'.../$pkgid.log' to '.../$compiler/$libname.log' (#3807).
* Added a new command, 'cabal reconfigure', which re-runs 'configure'
with the most recently used flags (#2214).
* Added add the '--index-state' flag for requesting a specific
version of the package index (#3893, #4115).
* Support for building Backpack packages. See
for more details.
* Support the Nix package manager (#3651).
* Made the 'template-haskell' package non-upgradable again (#4185).
* Fixed password echoing on MinTTY (#4128).
* Added a new solver flag, '--install-base-libraries', that allows
any package to be installed or upgraded (#4209).
* New 'cabal-install' command: 'outdated', for listing outdated
version bounds in a .cabal file or a freeze file (#4207).
* Added qualified constraints for setup dependencies. For example,
--constraint="setup.bar == 1.0" constrains all setup dependencies on
bar, and --constraint="foo:setup.bar == 1.0" constrains foo's setup
dependency on bar (part of #3502).
* Non-qualified constraints, such as --constraint="bar == 1.0", now
only apply to top-level dependencies. They don't constrain setup or
build-tool dependencies. The new syntax --constraint="any.bar == 1.0"
constrains all uses of bar.
* Added a technical preview version of the 'cabal doctest' command
18.104.22.168 Ryan Thomas <firstname.lastname@example.org> March 2016
* If there are multiple remote repos, 'cabal update' now updates
them in parallel (#2503).
* New 'cabal upload' option '-P'/'--password-command' for reading
Hackage password from arbitrary program output (#2506).
* Better warning for 'cabal run' (#2510).
* 'cabal init' now warns if the chosen package name is already
registered in the source package index (#2436).
* New 'cabal install' option: '--offline' (#2578).
* Accept 'builddir' field in cabal.config (#2484)
* Read 'builddir' option from 'CABAL_BUILDDIR' environment variable.
* Remote repos may now be configured to use https URLs. This uses
either curl or wget or, on Windows, PowerShell, under the hood (#2687).
* Install target URLs can now use https e.g. 'cabal install
* Automatically use https for cabal upload for the main
hackage.haskell.org (other repos will use whatever they are
configured to use).
* Support for dependencies of custom Setup.hs scripts
* 'cabal' program itself now can be used as an external setup
method. This fixes an issue when Cabal version mismatch caused
unnecessary reconfigures (#2633).
* Improved error message for unsatisfiable package constraints
* Fixed a space leak in 'cabal update' (#2826).
* 'cabal exec' and 'sandbox hc-pkg' now use the configured
* New 'cabal haddock' option: '--for-hackage' (#2852).
* Added a warning when the solver cannot find a dependency (#2853).
* New 'cabal upload' option: '--doc': upload documentation to
* Improved error handling for 'sandbox delete-source' (#2943).
* Solver support for extension and language flavours (#2873).
* Support for secure repos using hackage-security (#2983).
* Added a log file message similar to one printed by 'make' when
building in another directory (#2642).
* Added new subcommand 'init' to 'cabal user-config'. This
subcommand creates a cabal configuration file in either the
default location or as specified by --config-file (#2553).
* The man page for 'cabal-install' is now automatically generated
* The '--allow-newer' option now works as expected when specified
multiple times (#2588).
* New config file field: 'extra-framework-dirs' (extra locations
to find OS X frameworks in). Can be also specified as an argument
for 'install' and 'configure' commands (#3158).
* It's now possible to limit the scope of '--allow-newer' to
single packages in the install plan (#2756).
* Full '--allow-newer' syntax is now supported in the config file
(that is, 'allow-newer: base, ghc-prim, some-package:vector')
* Improved performance of '--reorder-goals' (#3208).
* Fixed space leaks in modular solver (#2916, #2914).
* Made the solver aware of pkg-config constraints (#3023).
* Added a new command: 'gen-bounds' (#3223). See
* Tech preview of new nix-style isolated project-based builds.
Currently provides the commands (new-)build/repl/configure.
22.214.171.124 Johan Tibell <email@example.com> January 2015
* New command: user-config (#2159).
* Implement 'cabal repl --only' (#2016).
* Fix an issue when 'cabal repl' was doing unnecessary compilation
* Prompt the user to specify source directory in 'cabal init'
* Remove the self-upgrade check (#2090).
* Don't redownload already downloaded packages when bootstrapping
* Support sandboxes in 'bootstrap.sh' (#2137).
* Install profiling and shared libs by default in 'bootstrap.sh'
126.96.36.199 Johan Tibell <firstname.lastname@example.org> June 2014
* Don't attempt to rename dist if it is already named correctly
* Treat all flags of a package as interdependent.
* Allow template-haskell to be upgradable again
188.8.131.52 Johan Tibell <email@example.com> May 2014
* Increase max-backjumps to 2000.
* Fix solver bug which led to missed install plans.
* Fix streaming test output.
* Tweak solver heuristics to avoid reinstalls.
184.108.40.206 Johan Tibell <firstname.lastname@example.org> May 2014
* Fix cabal repl search path bug on Windows
* Include OS and arch in cabal-install user agent
* Revert --constraint flag behavior in configure to 1.18 behavior
220.127.116.11 Johan Tibell <email@example.com> April 2014
* Build only selected executables
* Add -j flag to build/test/bench/run
* Improve install log file
* Don't symlink executables when in a sandbox
* Add --package-db flag to 'list' and 'info'
* Make upload more efficient
* Add --require-sandbox option
* Add experimental Cabal file format command
* Add haddock section to config file
* Add --main-is flag to init
0.14.0 Andres Loeh <firstname.lastname@example.org> April 2012
* Works with ghc-7.4
* Completely new modular dependency solver (default in most cases)
* Some tweaks to old topdown dependency solver
* Install plans are now checked for reinstalls that break packages
* Flags --constraint and --preference work for nonexisting packages
* New constraint forms for source and installed packages
* New constraint form for package-specific use flags
* New constraint form for package-specific stanza flags
* Test suite dependencies are pulled in on demand
* No longer install packages on --enable-tests when tests fail
* New "cabal bench" command
* Various "cabal init" tweaks
0.10.0 Duncan Coutts <email@example.com> February 2011
* New package targets: local dirs, local and remote tarballs
* Initial support for a "world" package target
* Partial fix for situation where user packages mask global ones
* Removed cabal upgrade, new --upgrade-dependencies flag
* New cabal install --only-dependencies flag
* New cabal fetch --no-dependencies and --dry-run flags
* Improved output for cabal info
* Simpler and faster bash command line completion
* Fix for broken proxies that decompress wrongly
* Fix for cabal unpack to preserve executable permissions
* Adjusted the output for the -v verbosity level in a few places
0.8.2 Duncan Coutts <firstname.lastname@example.org> March 2010
* Fix for cabal update on Windows
* On windows switch to per-user installs (rather than global)
* Handle intra-package dependencies in dependency planning
* Minor tweaks to cabal init feature
* Fix various -Wall warnings
* Fix for cabal sdist --snapshot
0.8.0 Duncan Coutts <email@example.com> Dec 2009
* Works with ghc-6.12
* New "cabal init" command for making initial project .cabal file
* New feature to maintain an index of haddock documentation
0.6.4 Duncan Coutts <firstname.lastname@example.org> Nov 2009
* Improve the algorithm for selecting the base package version
* Hackage errors now reported by "cabal upload [--check]"
* Improved format of messages from "cabal check"
* Config file can now be selected by an env var
* Updated tar reading/writing code
* Improve instructions in the README and bootstrap output
* Fix bootstrap.sh on Solaris 9
* Fix bootstrap for systems where network uses parsec 3
* Fix building with ghc-6.6
0.6.2 Duncan Coutts <email@example.com> Feb 2009
* The upgrade command has been disabled in this release
* The configure and install commands now have consistent behaviour
* Reduce the tendancy to re-install already existing packages
* The --constraint= flag now works for the install command
* New --preference= flag for soft constraints / version preferences
* Improved bootstrap.sh script, smarter and better error checking
* New cabal info command to display detailed info on packages
* New cabal unpack command to download and untar a package
* HTTP-4000 package required, should fix bugs with http proxies
* Now works with authenticated proxies.
* On Windows can now override the proxy setting using an env var
* Fix compatibility with config files generated by older versions
* Warn if the hackage package list is very old
* More helpful --help output, mention config file and examples
* Better documentation in ~/.cabal/config file
* Improved command line interface for logging and build reporting
* Minor improvements to some messages
0.6.0 Duncan Coutts <firstname.lastname@example.org> Oct 2008
* Constraint solver can now cope with base 3 and base 4
* Allow use of package version preferences from hackage index
* More detailed output from cabal install --dry-run -v
* Improved bootstrap.sh
0.5.2 Duncan Coutts <email@example.com> Aug 2008
* Suport building haddock documentaion
* Self-reinstall now works on Windows
* Allow adding symlinks to excutables into a separate bindir
* New self-documenting config file
* New install --reinstall flag
* More helpful status messages in a couple places
* Upload failures now report full text error message from the server
* Support for local package repositories
* New build logging and reporting
* New command to upload build reports to (a compatible) server
* Allow tilde in hackage server URIs
* Internal code improvements
* Many other minor improvements and bug fixes
0.5.1 Duncan Coutts <firstname.lastname@example.org> June 2008
* Restore minimal hugs support in dependency resolver
* Fix for disabled http proxies on Windows
* Revert to global installs on Windows by default
0.5.0 Duncan Coutts <email@example.com> June 2008
* New package dependency resolver, solving diamond dep problem
* Integrate cabal-setup functionality
* Integrate cabal-upload functionality
* New cabal update and check commands
* Improved behavior for install and upgrade commands
* Full Windows support
* New command line handling
* Bash command line completion
* Allow case insensitive package names on command line
* New --dry-run flag for install, upgrade and fetch commands
* New --root-cmd flag to allow installing as root
* New --cabal-lib-version flag to select different Cabal lib versions
* Support for HTTP proxies
* Improved cabal list output
* Build other non-dependent packages even when some fail
* Report a summary of all build failures at the end
* Partial support for hugs
* Partial implementation of build reporting and logging
* More consistent logging and verbosity
* Significant internal code restructuring
0.4 Duncan Coutts <firstname.lastname@example.org> Oct 2007
* Renamed executable from 'cabal-install' to 'cabal'
* Partial Windows compatibility
* Do per-user installs by default
* cabal install now installs the package in the current directory
* Allow multiple remote servers
* Use zlib lib and internal tar code and rather than external tar
* Reorganised configuration files
* Significant code restructuring
* Cope with packages with conditional dependencies
0.3 and older versions by Lemmih, Paolo Martini and others 2006-2007
* Switch from smart-server, dumb-client model to the reverse
* New .tar.gz based index format
* New remote and local package archive format