Install Koha on Ubuntu — Part 1: Introduction


Warn­ing: this tuto­r­ial was devel­oped in 2008, and is for ver­sions of Koha and Ubuntu that are now con­sid­ered quite old. If you want to install the cur­rent ver­sion of Koha on Ubuntu, please visit Koha on Ubuntu at the Koha Com­mu­nity wiki.

This six-part series will help you to install Koha.

Specif­i­cally, this guide is for installing Koha 3.0 on Ubuntu 8.10, but it might help you with other ver­sions of Linux and Koha too.

These arti­cles will begin at the ground level, walk­ing you through the instal­la­tion and con­fig­u­ra­tion of an Ubuntu Linux sys­tem from scratch. By the end of the series you should have a Koha sys­tem that you can use for eval­u­a­tion pur­poses. It’ll be a basic instal­la­tion using Koha’s inter­nal search engine rather than the more scal­able (and more com­plex) Zebra search engine.

If you plan to put Koha into pro­duc­tion for real-world Library use there are many other things you need to con­sider. The final arti­cle in the series, Going Live, dis­cusses this further.

Who this arti­cle is for.
  • Peo­ple who want to try Koha.
  • Peo­ple who aren’t nec­es­sar­ily Linux experts, but…
  • Who are very com­fort­able with com­put­ers and not afraid of using a command-line inter­face.
What to expect.

Caveats (Or “Why You Shouldn’t Lis­ten to Me”)

Oh, there are so very many rea­sons. Here are a few:

  • I’ve never con­fig­ured a pro­duc­tion Koha system.
  • I’m rel­a­tively new to Linux and have never admin­is­tered a pro­duc­tion Linux system.
  • Though I’m enrolled in an MLS pro­gram I haven’t worked sig­nif­i­cantly in a library.

Why This Might Help You Anyway

Just one reason:

  • I can prob­a­bly spare you some time-consuming learning.

In prepar­ing this guide I’ve installed Koha over a dozen times, care­fully doc­u­ment­ing prob­lems and solu­tions. I have sig­nif­i­cant expe­ri­ence in infor­ma­tion tech­nol­ogy and edu­ca­tion, and I’ve tried to use my back­ground to under­stand and explain what’s happening.


Com­mands you’ll type at a the com­mand line (aka a ter­mi­nal prompt) look like this:

sudo su
mkdir /build
cd /build

Nor­mally Linux guides pre­cede each com­mand with a “shell prompt” char­ac­ter: a $ for com­mands exe­cuted as an ordi­nary user and a # for com­mands exe­cuted as a supe­ruser (root).

Unfor­tu­nately fol­low­ing this con­ven­tion would pre­vent you from eas­ily copy­ing and past­ing com­mands into the ter­mi­nal win­dow, and copy-paste will spare you much time and many errors dur­ing this instal­la­tion. So this guide dis­re­gards con­ven­tion to make your life a lit­tle easier.


I’ve got­ten great help from the Koha mail­ing list and you can too. If you’re installing Koha I rec­om­mend sign­ing up for the list.

I also got help from two other instal­la­tion guides, both of which appear to have been removed.I very much appre­ci­ated the help they gave me beyond Koha’s included instal­la­tion files.

  • Installing Koha 3 Beta on Ubuntu Gutsy (Koha Wiki)
  • Installing Koha 3 on open­SUSE 11 (Koha Wiki)

Learn­ing More

You’ll find much more infor­ma­tion about Koha at and the Koha Library Soft­ware Com­mu­nity website.

Next Sec­tion…

Part 2: Prepar­ing Linux

There are 32 responses to this post.

By Vimal Kumar on December 22, 2008 at 12:00 am

Dear Andy,
Con­grats you to wrote a very very use­ful Koha 3 instal­la­tion for Ubuntu. My search for a nice Ubuntu-Koha doc­u­men­ta­tion ends here.

Your doc­u­men­ta­tion is help­ful for us. We are plan to orga­nize work­shops on Koha and wish to install koha for some libraries in my city.

Thank you again,
Vimal Kumar
Asst. Librar­ian
Asian School of Busi­ness


By Andy Giesler on December 29, 2008 at 3:13 pm

Thanks for let­ting me know, Vimal. I’m glad to hear you’ll find my tuto­r­ial helpful.

By Ken Yap on February 2, 2009 at 8:18 am

Thanks for that tute. I did it on 8.04.2 (for the LTS) and every­thing worked. Well, like you I didn’t opt for Zebra.

By Ben Ostrowsky on February 2, 2009 at 4:00 pm

Thanks for writ­ing this! There was a typo on page 7 (“Koga”); not sure if it appears any­where else.


By Andy Giesler on February 2, 2009 at 5:06 pm

Thanks for let­ting me know, Ben. I’ve fixed it and con­firmed it was just in that one place.

By Chuck on March 18, 2009 at 7:12 pm

Excel­lent guide. My eyes have gone fuzzy read­ing many, many install guides. This is one of the finest. Thanks!!!!

By Eric Hartnett on March 20, 2009 at 11:09 am

This is one of the best step-by-step guides I’ve ever seen for any­thing. Fol­low­ing your guide I was able to install Koha on Ubuntu 8.04 with­out a sin­gle prob­lem. Thanks for your hard work.

By Hilaire DOVONON on April 6, 2009 at 8:48 am

i just gonna try that tute; it’s seems a won­der­ful one to taste KOHA on Ubuntu. thanks !

By Luis Olguin - Argentina on June 1, 2009 at 2:39 pm

Bue­nas Tardes.
Felic­ita­ciones por este exce­lente tuto­r­ial acerca de Koha.

El unico incon­ve­niente que tuve fue con la insta­lación de Net::Z33950::ZOOM

Aparece error al eje­cu­tar los test.

Usando cpan force install Net::Z33950::ZOOM se puede com­ple­tar la instalación?.

Agrade­ceré su respuesta.

Luis oLguin — Argentina
Good evening.
Con­grat­u­la­tions on this excel­lent tuto­r­ial on Koha.

The only draw­back was that I had to install Net:: Z33950: ZOOM

Error appears when run­ning the test.

Using CPAN force install Net:: Z33950: ZOOM can com­plete the installation?.

I would appre­ci­ate your response.

Olguin Luis — Argentina

By Shiv on June 25, 2009 at 5:04 am

excel­lent descrip­tion works with ubuntu 9.04 also

By Shiv on June 25, 2009 at 5:07 am

u need to install by force,

> myhost # cpan
> cpan[1]> force install Net::Z3950::ZOOM
> cpan[2]> quit
> Lock­file removed.

By Ankit B on December 4, 2009 at 6:44 am

Using Ubuntu 9.04
When I open the browser :
It dis­plays this
pro­duc­tion mode — trapped fatal error

Help me it urgent


By Andy on December 5, 2009 at 2:23 am

Sorry Ankit, I’m not sure what would cause that error. A quick Google turned up this thread with some pos­si­ble solutions:—%22production-mode—trapped-fatal-error%22-td17071451.html

You might want to con­sider post­ing your ques­tion to the Koha mail­ing list. The tech­ni­cal peo­ple who are most active in the Koha com­mu­nity reg­u­larly fol­low that list and sug­gest solu­tions to prob­lems. You can sign up for the Koha mail­ing list here:

By Alberto on January 2, 2010 at 12:04 pm

You just saved my life. This tuto­r­ial is just what i needed. Thank you very much


By Andy on January 5, 2010 at 8:24 am

Glad I could help, Alberto. Thanks for let­ting me know.

By Michelle Fenger on February 14, 2010 at 10:03 pm

I installed ubuntu 9.10 and have tried to fol­low your EXCELLENT step by step tuto­r­ial. How­ever, when­ever I type the cd /build com­mand, I get
bash: cd: build: No such file or directory

Any sug­ges­tions? I have wanted to try Koha for a very long time, but have very min­i­mal linux expe­ri­ence so am hop­ing with your help and your tuto­r­ial I will be able to run a koha trial for my library.

Thank you


By Andy on February 15, 2010 at 4:14 pm


Thanks, glad you like the tuto­r­ial. I’ll con­tact you by email for more detailed diag­nos­tic questions.

One thing I do want to post for oth­ers to see, though, is advice on Linux exper­tise: I’d strongly advise against try­ing to go live with Koha until you have easy access to some­one with a good bit of Linux/Unix expe­ri­ence. That’s less impor­tant when set­ting up a sam­ple sys­tem to play with, but I wouldn’t want to go live with­out a good option for on-site tech­ni­cal support.

By Michelle on February 15, 2010 at 6:15 pm

Thanks for con­tact­ing me by email and I will give your sug­ges­tions a try.

I def­i­nitely take your warn­ing to heart about hav­ing an expert in linux to help. Cur­rently I am using this as my next step in intro­duc­ing myself to linux. I’ve waited this long to get this far, I’m in no hurry to make mis­takes. Thanks for your help and I’m sure I’ll be back to ask more.

By mdwafi on March 11, 2010 at 3:46 am

Hi Andy,

Nice job. Congrats…

I’ve prob­lem when installing Perl mod­ules. Is it any other way to install all the mod­ules with­out using the CPAN?

Thank You..


By Andy on March 11, 2010 at 9:34 am

Most of my expe­ri­ence with mod­ules has been using CPAN. In the one case where I couldn’t get CPAN to work I installed the mod­ule man­u­ally. There’s an exam­ple of that process at the top of the “Perl Mod­ules” page:

I’m not at all a Linux expert, though, and there might be other ways. If those two meth­ods don’t work you might want to try post­ing some­thing in a Linux help forum.

You might also find more help on the Koha mail­ing list. Infor­ma­tion on sign­ing up for the list is at

By Fips on March 16, 2010 at 5:07 am

Excel­lent write-up, and beau­ti­fully pre­sented! Thanks for the hard work, you made installing this soft­ware at least three headaches lighter.

By Galen Charlton on April 8, 2010 at 4:57 pm

Ear­lier today I did some work on a Koha data­base installed by a library who fol­lowed your instruc­tions. There was a minor glitch — as it turns out, indi­cated that the wrong SAX parser was being used. To resolve the prob­lem, it was nec­es­sary to update /usr/local/share/perl/5.8.8/XML/SAX/ParserDetails.ini, rather than (as your instruc­tions state) /etc/perl/XML/SAX/ParserDetails.ini. I’m not sure whether that was just some local cir­cum­stance or a con­se­quence of the instruc­tion to install XML::LibXML::SAX::Parser from CPAN, but it may be worth a note in the instructions.


By Andy on April 12, 2010 at 8:49 am

Thanks for not­ing that. I’ll look into it and may make an update. I do remem­ber hav­ing more trou­ble with the SAX parser than any other part of the install. There might be some vari­a­tion between Ubuntu instal­la­tions for some reason.

By Abdullah-Al-Modabber on October 28, 2010 at 12:26 am

Thank you very much for pro­vid­ing such a use­ful tutorial.

Unfor­tu­nately I faced the fol­low­ing prob­lem as I tried to login in admin page:

Koha error

The fol­low­ing fatal error has occurred:

Access denied for user ‘kohaadmin’@‘localhost’ (using pass­word: YES) at /usr/share/koha/lib/C4/ line 646.
Com­pi­la­tion failed in require at /usr/share/koha/lib/C4/ line 25.
BEGIN failed–compilation aborted at /usr/share/koha/lib/C4/ line 25.
Com­pi­la­tion failed in require at /usr/share/koha/lib/C4/ line 24.
BEGIN failed–compilation aborted at /usr/share/koha/lib/C4/ line 24.
Com­pi­la­tion failed in require at /usr/share/koha/lib/C4/ line 27.
BEGIN failed–compilation aborted at /usr/share/koha/lib/C4/ line 27.
Com­pi­la­tion failed in require at /usr/share/koha/lib/C4/ line 31.
BEGIN failed–compilation aborted at /usr/share/koha/lib/C4/ line 31.
Com­pi­la­tion failed in require at /usr/share/koha/opac/cgi-bin/opac/errors/ line 21.
BEGIN failed–compilation aborted at /usr/share/koha/opac/cgi-bin/opac/errors/ line 21.

Could you please help me how to solve the poblem?


By Andy on October 28, 2010 at 2:01 pm

Unfor­tu­nately I haven’t seen that error myself.

Since it seems related to per­mis­sions, it might help to review the page on installing Koha itself, espe­cially “Con­fig­ure Linux Per­mis­sions” and “Con­fig­ure MySQL”, to con­firm whether you went through all of the steps com­pletely. You can find that page here (

Also, I Googled your error mes­sage and at the top of the results were two dis­cus­sion threads that seem to be about the same prob­lem. You can find the threads here ( and here (

Finally, if that doesn’t resolve the prob­lem, I rec­om­mend sign­ing up for the Koha Mail­ing List ( and post­ing your ques­tion there if you haven’t already.

Best of luck.

By Mridul Adhikary on December 1, 2010 at 11:07 pm

Is it pos­si­ble to access AACR2R card for­mat by using most update ver­sion of Koha ?

By sudath on May 1, 2011 at 4:45 am

Here i pub­lished arti­cle Install Koha on Ubuntu 10.10
each and every steps are described.
all are welcome

By sajib on November 26, 2011 at 12:47 pm

Thanks Mr. Andy bcz of this is best doc­u­men­ta­tion about koha , i am try­ing to install koha in my organization,I think i will be todone it.

Thanks again

By mutendemari fortunate on March 13, 2012 at 9:04 am

iam very inter­ested in using koha inter­grated library system

By Install Koha on Ubuntu — Part 4: Koha » Blazing Moon on July 30, 2012 at 4:09 pm

[…] Part 1: Introduction […]

By Install Koha on Ubuntu — Part 5: Testing » Blazing Moon on July 30, 2012 at 4:10 pm

[…] Part 1: Introduction […]

By azam on February 6, 2013 at 11:28 pm

we need this software

You aren't currently logged in. You can use the fields below to post a comment without logging in or registering, or you can log in or register now.

By submitting a comment here you grant Blazing Moon a perpetual license to reproduce your words and name/web site in attribution. Inappropriate comments will be removed at admin's discretion.

Blazing Moon RSS Feed