Installing CKAN from source

This section describes how to install CKAN from source. Although Installing CKAN from package is simpler, it requires Ubuntu 18.04 64-bit or Ubuntu 16.04 64-bit. Installing CKAN from source works with other versions of Ubuntu and with other operating systems (e.g. RedHat, Fedora, CentOS, OS X). If you install CKAN from source on your own operating system, please share your experiences on our How to Install CKAN wiki page.

For Python 3 installations, the minimum Python version required is 3.6

  • Ubuntu 18.04 includes Python 3.6 as part of its distribution
  • Ubuntu 16.04 includes Python 3.5 as part of its distribution

From source is also the right installation method for developers who want to work on CKAN.

1. Install the required packages

If you’re using a Debian-based operating system (such as Ubuntu) install the required packages with this command:

sudo apt-get install python3-dev postgresql libpq-dev python3-pip python3-venv git-core solr-jetty openjdk-8-jdk redis-server


For Python 2 (deprecated, but compatible with CKAN 2.9 and earlier), do this instead:

sudo apt-get install python-dev postgresql libpq-dev python-pip python-virtualenv git-core solr-tomcat openjdk-8-jdk redis-server

If you’re not using a Debian-based operating system, find the best way to install the following packages on your operating system (see our How to Install CKAN wiki page for help):

Package Description
Python The Python programming language, v3.6 or newer (or v2.7)
PostgreSQL The PostgreSQL database system, v9.5 or newer
libpq The C programmer’s interface to PostgreSQL
pip A tool for installing and managing Python packages
python3-venv The Python3 virtual environment builder (or for Python 2 use ‘virtualenv’ instead)
Git A distributed version control system
Apache Solr A search platform
Jetty An HTTP server (used for Solr).
OpenJDK JDK The Java Development Kit (used by Jetty)
Redis An in-memory data structure store

2. Install CKAN into a Python virtual environment


If you’re installing CKAN for development and want it to be installed in your home directory, you can symlink the directories used in this documentation to your home directory. This way, you can copy-paste the example commands from this documentation without having to modify them, and still have CKAN installed in your home directory:

mkdir -p ~/ckan/lib
sudo ln -s ~/ckan/lib /usr/lib/ckan
mkdir -p ~/ckan/etc
sudo ln -s ~/ckan/etc /etc/ckan
  1. Create a Python virtual environment (virtualenv) to install CKAN into, and activate it:

    sudo mkdir -p /usr/lib/ckan/default
    sudo chown `whoami` /usr/lib/ckan/default
    python3 -m venv /usr/lib/ckan/default
    . /usr/lib/ckan/default/bin/activate


The final command above activates your virtualenv. The virtualenv has to remain active for the rest of the installation and deployment process, or commands will fail. You can tell when the virtualenv is active because its name appears in front of your shell prompt, something like this:

(default) $ _

For example, if you logout and login again, or if you close your terminal window and open it again, your virtualenv will no longer be activated. You can always reactivate the virtualenv with this command:

. /usr/lib/ckan/default/bin/activate


For Python 2 then replace the python3 -m venv command with:

virtualenv --python=/usr/bin/python2.7 --no-site-packages /usr/lib/ckan/default
. /usr/lib/ckan/default/bin/activate
  1. Install the recommended setuptools version and up-to-date pip:

    pip install setuptools==44.1.0
    pip install --upgrade pip
  2. Install the CKAN source code into your virtualenv.

    To install the current stable release of CKAN (CKAN 2.9.7), run:

    pip install -e 'git+[requirements]'


    For Python 2 replace the last fragment with requirements-py2

    pip install -e 'git+[requirements-py2]'

    If you’re installing CKAN for development, you may want to install the latest development version (the most recent commit on the master branch of the CKAN git repository). In that case, run this command instead:

    pip install -e 'git+[requirements,dev]'


    The development version may contain bugs and should not be used for production websites! Only install this version if you’re doing CKAN development.

  3. Deactivate and reactivate your virtualenv, to make sure you’re using the virtualenv’s copies of commands like ckan rather than any system-wide installed copies:

    . /usr/lib/ckan/default/bin/activate

3. Setup a PostgreSQL database



If you are facing a problem in case postgresql is not running, execute the command sudo service postgresql start

Check that PostgreSQL was installed correctly by listing the existing databases:

sudo -u postgres psql -l

Check that the encoding of databases is UTF8, if not you might find issues later on with internationalisation. Since changing the encoding of PostgreSQL may mean deleting existing databases, it is suggested that this is fixed before continuing with the CKAN install.

Next you’ll need to create a database user if one doesn’t already exist. Create a new PostgreSQL user called ckan_default, and enter a password for the user when prompted. You’ll need this password later:

sudo -u postgres createuser -S -D -R -P ckan_default

Create a new PostgreSQL database, called ckan_default, owned by the database user you just created:

sudo -u postgres createdb -O ckan_default ckan_default -E utf-8


If PostgreSQL is run on a separate server, you will need to edit postgresql.conf and pg_hba.conf. On Ubuntu, these files are located in etc/postgresql/{Postgres version}/main.

Uncomment the listen_addresses parameter and specify a comma-separated list of IP addresses of the network interfaces PostgreSQL should listen on or ‘*’ to listen on all interfaces. For example,

listen_addresses = 'localhost,'

Add a line similar to the line below to the bottom of pg_hba.conf to allow the machine running the web server to connect to PostgreSQL. Please change the IP address as desired according to your network settings.

host    all             all                    md5

4. Create a CKAN config file

Create a directory to contain the site’s config files:

sudo mkdir -p /etc/ckan/default
sudo chown -R `whoami` /etc/ckan/

Create the CKAN config file:

ckan generate config /etc/ckan/default/ckan.ini

Edit the ckan.ini file in a text editor, changing the following options:


This should refer to the database we created in 3. Setup a PostgreSQL database above:

sqlalchemy.url = postgresql://ckan_default:pass@localhost/ckan_default

Replace pass with the password that you created in 3. Setup a PostgreSQL database above.


If you’re using a remote host with password authentication rather than SSL authentication, use:

sqlalchemy.url = postgresql://ckan_default:pass@<remotehost>/ckan_default?sslmode=disable

Each CKAN site should have a unique site_id, for example:

ckan.site_id = default

Provide the site’s URL (used when putting links to the site into the FileStore, notification emails etc). For example:

ckan.site_url =

Do not add a trailing slash to the URL.

5. Setup Solr


CKAN uses Solr as its search platform, and uses a customized Solr schema file that takes into account CKAN’s specific search needs. Now that we have CKAN installed, we need to install and configure Solr.


These instructions explain how to deploy Solr using the Tomcat web server, but CKAN doesn’t require Tomcat - you can deploy Solr to another web server, such as Jetty, if that’s convenient on your operating system.

  1. Change the default port Tomcat runs on (8080) to the one expected by CKAN. To do so change the following line in the /etc/tomcat9/server.xml file (tomcat8 in older Ubuntu versions):

    <Connector port="8080" protocol="HTTP/1.1"
    <Connector port="8983" protocol="HTTP/1.1"


    This is not required by CKAN, you can keep the default Tomcat port or use a different one, just make sure to update the solr_url setting in your CKAN configuration file accordingly.

  2. Replace the default schema.xml file with a symlink to the CKAN schema file included in the sources.

    sudo mv /etc/solr/conf/schema.xml /etc/solr/conf/schema.xml.bak
    sudo ln -s /usr/lib/ckan/default/src/ckan/ckan/config/solr/schema.xml /etc/solr/conf/schema.xml
  3. Now restart Solr (use tomcat8 on older Ubuntu versions):

    sudo service tomcat9 restart

    Check that Solr is running by opening http://localhost:8983/solr/


    On Ubuntu 18.04 and older, instead of the Solr UI you may see an Internal Server Error page with a message containing: Cannot create directory: /var/lib/solr/data/index

    This is caused by a bug and you need to run some extra commands to fix it:

    sudo mv /etc/systemd/system/tomcat9.d /etc/systemd/system/tomcat9.service.d
    sudo systemctl daemon-reload
    sudo service tomcat9 restart
  4. Finally, change the solr_url setting in your CKAN configuration file (/etc/ckan/default/ckan.ini) to point to your Solr server, for example:


7. Create database tables

Now that you have a configuration file that has the correct settings for your database, you can create the database tables:

cd /usr/lib/ckan/default/src/ckan
ckan -c /etc/ckan/default/ckan.ini db init

You should see Initialising DB: SUCCESS.


If the command prompts for a password it is likely you haven’t set up the sqlalchemy.url option in your CKAN configuration file properly. See 4. Create a CKAN config file.

8. Set up the DataStore


Setting up the DataStore is optional. However, if you do skip this step, the DataStore features will not be available and the DataStore tests will fail.

Follow the instructions in DataStore extension to create the required databases and users, set the right permissions and set the appropriate values in your CKAN config file.

Once you have set up the DataStore, you may then wish to configure either the DataPusher or XLoader extensions to add data to the DataStore. To install DataPusher refer to this link: and to install XLoader refer to this link:

9. You’re done!

You can now run CKAN from the command-line. This is a simple and lightweight way to serve CKAN that is useful for development and testing:

cd /usr/lib/ckan/default/src/ckan
ckan -c /etc/ckan/default/ckan.ini run

Open in a web browser, and you should see the CKAN front page.

Now that you’ve installed CKAN, you should:

  • Run CKAN’s tests to make sure that everything’s working, see Testing CKAN.
  • If you want to use your CKAN site as a production site, not just for testing or development purposes, then deploy CKAN using a production web server such as uWSGI or Nginx. See Deploying a source install.
  • Begin using and customizing your site, see Getting started.


The default authorization settings on a new install are deliberately restrictive. Regular users won’t be able to create datasets or organizations. You should check the Organizations and authorization documentation, configure CKAN accordingly and grant other users the relevant permissions using the sysadmin account.

Source install troubleshooting

Solr setup troubleshooting

Solr requests and errors are logged in the web server log files.

  • For Jetty servers, the log files are:

  • For Tomcat servers, they’re:


Unable to find a javac compiler

If when running Solr it says:

Unable to find a javac compiler; is not on the classpath. Perhaps JAVA_HOME does not point to the JDK.

See the note in 5. Setup Solr about JAVA_HOME. Alternatively you may not have installed the JDK. Check by seeing if javac is installed:

which javac

If javac isn’t installed, do:

sudo apt-get install openjdk-8-jdk

and then restart Solr:

For Ubuntu 18.04:

sudo service jetty9 restart

or for Ubuntu 16.04:

sudo service jetty8 restart

AttributeError: ‘module’ object has no attribute ‘css/main.debug.css’

This error is likely to show up when debug is set to True. To fix this error, install frontend dependencies. See Frontend development guidelines.

After installing the dependencies, run npm run build and then start ckan server again.

If you do not want to compile CSS, you can also copy the main.css to main.debug.css to get CKAN running:

cp /usr/lib/ckan/default/src/ckan/ckan/public/base/css/main.css \

ImportError: No module named ‘flask_debugtoolbar’

This may show up if you have enabled debug mode in the config file. Simply install the development requirements:

pip install -r /usr/lib/ckan/default/src/ckan/dev-requirements.txt