Ubuntu-provided CouchDB

Depending on your Ubuntu release, CouchDB availability varies. Newer versions of Ubuntu have a recent CouchDB included in their respective software repositories. You can install CouchDB with the Ubuntu Software Center, or from the command line with the apt-get or aptitude utilities, which ever you prefer. However, to get the newest version of CouchDB you may have to install from source, or other package repositories that have newer pre-built CouchDB packages.

Ubuntu Release

CouchDB Version


Saucy 13.10

CouchDB 1.4.0

Use and Abuse

Raring 13.04

CouchDB 1.2.1

Build from Source

Precise 12.04

CouchDB 1.2.1


Oneiric 11.10

CouchDB 1.0.4

Build from Source

Natty 11.04

CouchDB 1.0.4

Build from Source

Lucid 10.04

CouchDB 1.0.4

Build from Source

All older releases

Not Supported, Embarrassingly Old

Cry From Shame

Installing using an existing package

sudo apt-get install couchdb -y


If the aptitude/apt-get installation gives an error message then couchdb might not have access to its pid file.


sudo chown -R couchdb /var/run/couchdb

Need to rerun the setup script:

sudo dpkg --configure couchdb

For older releases of Ubuntu we strongly recommend to build from source.

Installing from Source on Precise, Quantal, Raring, and Saucy

Download CouchDB from an apache mirror.

### make sure you have a couchdb user for the daemon, and couchb group also
## get developer tools dependencies
sudo apt-get install -y g++
sudo apt-get install -y erlang-dev erlang-manpages erlang-base-hipe erlang-eunit erlang-nox erlang-xmerl erlang-inets
### other packages that are not required but may be useful
# - require GUI packages / X
# sudo apt-get install -y erlang-observer erlang-appmon erlang-debugger erlang-et
# - useful erlang tools to develop with
# sudo apt-get install -y erlang-dialyzer erlang-percept erlang-typer erlang-edoc erlang-os-mon erlang-runtime-tools erlang-inviso erlang-tools

### couchdb developer dependencies
sudo apt-get install -y libmozjs185-dev libicu-dev libcurl4-gnutls-dev libtool
### unpack source
cd /tmp && tar xvzf apache-couchdb-1.4.0.tar.gz
cd apache-couchdb-*
./configure && make
### install
sudo make install

### remove leftovers from ubuntu packages
sudo rm /etc/logrotate.d/couchdb /etc/init.d/couchdb

### install logrotate and initd scripts
sudo ln -s /usr/local/etc/logrotate.d/couchdb /etc/logrotate.d/couchdb
sudo ln -s /usr/local/etc/init.d/couchdb  /etc/init.d
sudo update-rc.d couchdb defaults

Alternatively: using build-couchdb

There is a project called build-couchdb that automates and simplifies the building of CouchDB and its dependencies. If you want to build the newest version of Couch with the least amount of pain this is probably your best bet. See the project Readme for instructions.

# Add couchdb user account useradd -d /var/lib/couchdb couchdb chown -R couchdb: /var/lib/couchdb /var/log/couchdb

# next two steps fix problems where adding admin hangs or setting admins in local.ini hangs the start. Also fixes problems with reader_acl test. chown -R root:couchdb /etc/couchdb chmod 664 /etc/couchdb/*.ini chmod 775 /etc/couchdb/*.d

# start couchdb /etc/init.d/couchdb start # Start couchdb on system start update-rc.d couchdb defaults

# Verify couchdb is running curl # {"couchdb":"Welcome","version":"1.0.1"} }}}

Example 1 (Alternate)

The default installation of Ubuntu desktop 10.04 has a lot of version 0.10.0 CouchDB files and I did not want to worry about having them mixed with my source installed files.

This set of install instructions is modified from Example 1 and places all current CouchDB files within the /usr/local/ tree. Any other CouchDB related files outside of /usr/local/ can be deleted or ignored.

sudo su
# Install dependencies required to build couchdb from source
apt-get build-dep couchdb
cd /opt
# download the latest release from http://couchdb.apache.org/downloads.html
# wget <url>
tar xvzf apache-couchdb-x.xx.x.tar.gz
cd apache-couchdb-x.xx.x

# Note: To install couchdb in the default location use --prefix= in the configure statement
# Note: To check what XULRunner version you have installed use xulrunner -v. CouchDB-1.1.x and older will not work with XULRunner 2.0+.

# Note: See Additional Notes (below) for additional, necessary information about using CouchDB-1.1.x and older on Ubuntu versions less than 11.04.
# Note: The extra --with-js-* options should not be used with CouchDB-1.2 (current trunk) and newer on Ubuntu 11.04+, where building against libmozjs185-dev is preferred.

./configure --prefix=/usr/local/ --with-js-lib=/usr/lib/xulrunner-devel-1.9.x.y/lib --with-js-include=/usr/lib/xulrunner-devel-1.9.x.y/include

# Test installation, you will have problems regarding libmozjs and xulrunner here if you have not already corrected them
make check

# Now you can compile and install couchdb
make && make install

# vi /etc/passwd here and change home directory to /usr/local/var/lib/couchdb/, couchdb user is created during make && make install

# change file ownership from root to couchdb user and adjust permissions
chown -R couchdb: /usr/local/var/{lib,log,run}/couchdb /usr/local/etc/couchdb
chmod 0770 /usr/local/var/{lib,log,run}/couchdb/
chmod 664 /usr/local/etc/couchdb/*.ini
chmod 775 /usr/local/etc/couchdb/*.d

# start couchdb
cd /etc/init.d
ln -s /usr/local/etc/init.d/couchdb couchdb
/etc/init.d/couchdb start
# Start couchdb on system start
update-rc.d couchdb defaults

# Verify couchdb is running
# {"couchdb":"Welcome","version":"1.0.1"}

# run test suite in firefox at

Example 2 (with minimal dependencies)

Tested with CouchDB versions: 0.11.0, 1.0.0

This example is especially useful when using a minimal Ubuntu, rather than a full desktop one, as it won't install as many packages as the previous example.


First, install SpiderMonkey from source, as described here (this should prevent the possible xulrunner issues described later).

Second, install the rest of the dependencies:

sudo apt-get install libicu-dev libcurl4-gnutls-dev libtool erlang-dev erlang

Note: Without the 'erlang' package, couchdb could still be installed, but would be missing important erlang libraries and won't run properly.



# install:
tar zxvf apache-couchdb-${couch_v}.tar.gz
cd apache-couchdb-${couch_v}
./configure --prefix=${prefix}
make && sudo make install

# add couchdb user:
sudo useradd -d ${prefix}/var/lib/couchdb couchdb

# correct permissions:
sudo chown -R couchdb: ${prefix}/var/{lib,log,run}/couchdb ${prefix}/etc/couchdb
sudo chmod 0770 ${prefix}/var/{lib,log,run}/couchdb ${prefix}/etc/couchdb

Additional Notes

Problems after upgrading from source

If you have previously built and installed from source it is likely that there will be a previous version of the Erlang libraries (couch-x.x.x, erlang-oauth, etap, ibrowse-x.x.x, mochiweb-xxx) in /usr/local/lib/couchdb/erlang/lib. These should be removed before doing sudo make install for the new version. If you only discover a problem (e.g., CouchDB crashes) after doing the new install, the problem might be solved by manually removing everything in /usr/local/lib/couchdb/erlang/lib and redoing sudo make install.

Problems with libmozjs and xulrunner?

In Ubuntu 10.04 you may get an error similar to this:

OS Process Error <0.4649.0> :: {os_process_error,{exit_status,127}}
/opt/couchdb/lib/couchdb/bin/couchjs: error while loading shared libraries: libmozjs.so: cannot open shared object file: No such file or directory

This is can be resolved by creating an xulrunner configuration as follows:

sudo vi /etc/ld.so.conf.d/xulrunner.conf

Note: To check what XULRunner version you have installed use xulrunner -v

Then add the following lines to the file (You may need to change the library version to match whats installed):


Once the configuration files is created and saved, you will need to run ldconfig:

sudo /sbin/ldconfig

This solution is referenced in bug report #557275.

Installing spidermonkey from source

This has been tested on Ubuntu 8.04 Server, with couchdb 1.2.0, from source.

install_spidermonkey_ ( ) {
    cd /tmp
    wget http://ftp.mozilla.org/pub/mozilla.org/js/${SPIDERMONKEY_VER}.tar.gz
    tar xvzf ${SPIDERMONKEY_VER}.tar.gz
    cd ${SPIDERMONKEY_DIR}/js/src
    make distclean 2> /dev/null # Just in case it is dirty
    make clean
    sudo make install
    sudo ldconfig # Make sure the new libraries are reachable

And then, to build couch:

./configure --with-js-lib=${JS_LIB} --with-js-include=${JS_INCLUDE}

Note: because the libtools in Ubuntu 8.04 are old, the macro LT_INIT is not supported. To install CouchDB 1.2.0, some hacking must be performed on the configure script:

sed -i -e 's/^LT_INIT/#LT_INIT/' configure

System updates

When performing system updates (using apt-get or package manager) please keep in mind that the /etc/ld.so.conf.d/xulrunner.conf file is not maintained by the system and will not be updated if a new version of xulrunner is deployed!

So please check the update content in order to determine if the xulrunner package is being updated, then make sure that you update the configuration file with new version number.

You can use the following command line in order to update your xulrunner configuration:

find /usr/lib -maxdepth 1 -type d -name "xulrunner-*" | grep -v 'addons' > /tmp/new.xulrunner.conf && sudo cp /tmp/new.xulrunner.conf /etc/ld.so.conf.d/xulrunner.conf && sudo /sbin/ldconfig

You need to re-start your couchdb server after the library configuration update!

Don't forget to configure logging!

Setup log rotate

First off, a lot of people run CouchDB from source which means that in 99% of all installs, the log rotation is not activated.

To fix this (on Ubuntu/Debian), do the following:

sudo ln -s /usr/local/etc/logrotate.d/couchdb /etc/logrotate.d/couchdb

Don't forget to change the path to match your installation.

Make sure to familiarize yourself with log rotate. Depending on the space requirements and business of your installation, you should adjust your configuration so that you don't run out of disk space. If CouchDB is unable to log, it will crash.

Adjust the log level

In most cases it's more than alright to just run with a log level of error.

Add the following to your local.ini (in [log]): level = error Log directory

If you are still running out of diskspace? Add the following to your local.ini (in [log]):

file = /path/to/more/diskspace/couch.log

... if you adjusted the above, you will need to correct the config for logrotate.d as well.

No logging

Last but not least — if no logs are needed, just turn them off completely.

These logging tips are based on the recommendations found on Till Klampäckel's Blog article Operating CouchDB.

Note on installing on Ubuntu Desktop flavors

If you're not running Ubuntu server, but rather running some variant of Ubuntu desktop, I'd strongly recommend compiling from source and keeping the default prefix of /usr/local. Ubuntu comes standard with couchdb-bin, and uses desktop-couch with tools like Ubuntu One, gwibber, and evolution. But, Lucid Lynx ships with version 0.10.0. This is a long-term support item, but that doesn't mean Canonical will be releasing 0.11 anytime soon.

So, to install a parallel version of current CouchDB on an Ubuntu desktop system, you should download build from source, being careful to keep the default install prefix of /usr/local, and following all of the above instructions about libraries and dependencies.

Then, after installing CouchDB, you can still get it to start at boot as normal, but because 0.11.x is in /usr/local, just running

sudo update-rc.d couchdb defaults

is probably not going to do the right thing. What is seems to do is look in the /etc/init.d directory, where it will likely find the 0.10 version of CouchDB.

Instead, you have force the system to use the version of CouchDB installed in /usr/local. There should be an option to update-rc.d that will tell it to look in /usr/local/etc rather than /etc, but I couldn't find it.

A brute force way to make it work is to do something like:

sudo mv /etc/init.d/couchdb /etc/init.d/couchdb.0.10.donotuse
sudo ln -sf /usr/local/etc/init.d/couchdb /etc/init.d/couchdb
sudo update-rc.d couchdb defaults

External Articles

Installing_on_Ubuntu (last edited 2014-04-01 20:39:03 by 67)