How to Add Custom Fields to CKAN 2.0

MarinaMartin edited this page Apr 21, 2013 · 2 revisions
Clone this wiki locally

Note: This method works, but is surely not the most efficient method – it's just the only way I could get it to work. Edits from core CKAN contributors appreciated.

In order to add custom fields, you need to create and customize an extension. (Relax! This seems intimidating, but once it's installed, this is pretty easy.)

Generate file

SSH into your running CKAN instance as normal, e.g.

ssh -i your.pem

Change to your pyenv directory, e.g.

cd ~/public_html/

Activate pyenv, e.g.

. pyenv/bin/activate

Run this command to generate the setup wizard, replacing MYEXTENSION with what you'd like to name yours. Answer the questions as the wizard walks you through.

paster create -t ckanext ckanext-MYEXTENSION

This will create a new directory in the current directory named ckanext-MYEXTENSION. Change into this directory:

cd ckanext-MYEXTENSION

Open the file:

sudo nano

Copy its contents to a local file.

Put extension on Github

Create Github repo

Sign in to Create a new repository.

Create local git repo

Create a new directory on your local machine, e.g.

mkdir ckanext-MYEXTENSION

Change into this directory:

cd ckanext-MYEXTENSION

Initiatilize a git repo:

git init

Create a README file to get the repo going:

touch README

Add the README to the repo:

git add .
git commit -am "First commit"
git push

NOTE: If you already pushed an initial README to your Github repo and are blocked here, try:

git push --force

Create extension files

You can see an example of these files at: and

Top-level directory

In your MAIN (top-level) git repo directory on your local machine, e.g. ckanext-MYEXTENSION, create a file named “” and paste the contents of the generated earlier.

sudo nano

Also create a blank file:


Now create a new directory called ckanext:

mkdir ckanext

Switch to this directory:

cd ckanext

ckanext directory

Create a new file containing the following:

  import pkg_resources
except ImportError:
  import pkgutil
  __path__ = pkgutil.extend_path(__path__, __name__)

Create a directory for your extension and change to it:



Create a blank and file:


Create a templates directory and change into it:

mkdir templates

templates directory

Create a package directory and change into it:

mkdir package
cd package

package directory

Create a blank read.html file:

touch read.html

Create a snippets directory and change into it:

mkdir snippets
cd snippets

snippets directory

Create two blank files:

touch package_basic_fields.html
touch package_metadata_fields.html

Customize extension fields

Update the following files with the contents of


Customize these files for the needs of your custom fields.


Modify the file in your top-level directory. Under where it says Add Plugins here, uncomment and update:

# Add plugins here, eg

Replace MYEXTENSION with the exact same value as your MYEXTENSION directory name from above. Replace YOURPLUGIN with the name of the plugin class inside, e.g.


Push changes to git

git add .
git commit -am "Pushing extension"
git push

Install on your CKAN server

Make sure you are SSHed into your CKAN environment for this step!

sudo pip install -e git+


sudo pip install -e git+

Now edit your development.ini and add the extension to your list of plugins:

sudo nano development.ini
ckan.plugins = MYEXTENSION


ckan.plugins = stats json_preview recline_preview datastore usmetadata

Restart your production server if needed:

sudo service apache2 restart

Now your custom fields should appear on your dataset packages!