This page is
an outgrowth of the efforts of members at the former tyrannozaurus forums to put up a comprehensive wiki on how to install an IPK, including information on how to prevent and
resolve any problems with installation.
It still has some rough spots, and if you have any suggestions for improvement, or can help with information to answer any questions or incomplete sections,
feel free to contact me.
If you feel you need to use a translation engine
to read this page, I recommend using http://babelfish.altavista.com,
instead of other translation services, because
their software does a better job of translating
code than the other services I have tested on my
site. And, if you find a page on my site that does
not translate well using babelfish, please tell me so I can attempt
to improve the page.
If you wish to skip the rest of this introduction and just go to the table of contents, click here.
This guide still can use fine tuning. Please help me fill in some of the information
gaps if you can,
and also let me know if you find a section you needed
that was not helpful enough.
I also especially need feedback from OpenZaurus, pdaX, and Angstrom users about the specifics for their ROMs, and confirmation from Sharp/Cacko users that I have got our info correct about directories.
While there may be newer Zaurus ROMs I am not referring to above or below, the basics of IPK installation remain the same, and I remain happy to add specific examples for other ROMs if anyone wants to assist by providing the information.
So, corrections, answers to my questions and more troubleshooting tips from everyone continue to be welcome.
If you have favorite web resources on this topic, please also share their URLs.
I know we have community members who know much, much more
than I do about ipk installation and troubleshooting.
So, I see myself as more of an editor, helping to
pull together the information available, contributing
from my own experience when I can.
You can install IPKs using either the GUI Installer
or the command line on your Zaurus.
Some of the following suggestions for what to do if you get into trouble
trying to install an IPK can only be performed from
the command line, while others can be done using
a GUI File Manager, and the System Info Tab.
In most cases, you will need to install a console
in order to adequately debug any problems.
These instructions were primarily written from the vantage point of
someone wanting guidance on how to prevent or debug problems
with installing IPKs which are downloaded to the Zaurus before installation, as a separate step.
However, most of the debugging suggestions made here should still apply for installing packages directly from a Package Feed using the GUI Installer.
A succinct summary of instructions for installing software to Qtopia devices can also be found here:
Before attempting to download or install an IPK,
it is absolutely essential to make sure you have
chosen an IPK that is compatible with your model
and ROM. The best way to insure this is to get
the IPK from a feed for your specific ROM, or get
the ipk from someone using your ROM and model.
Official feeds are probably a better bet as private
feeds often still have IPKs on them that were used
by the owner on other models or ROMs before upgrading,
and can include IPKs the owner tested or never succeeded
or attempted to install.
A fairly good list of Zaurus Feeds could formerly be found
about halfway down the page of historic Community Links at
(see NOTE below about tyrannozaurus URLs):
http://www.tyrannozaurus.com/?q=userlink/all, or see the formerly current list at
For more information about checking the compatibility of specific IPKs, also see the
section below on formats.
If you already know how to use the Zaurus' built-in installation software, I suggest skipping this newbie installation section and going to one of the next sections about installing a
console and a
file manager, or about
locating the ipk.
Unlike on Windows or the Mac, trouble-free installation of software on the zaurus is not just a matter of pointing and clicking on a link to a package you want from the web or on a CD,
and immediately being guided through a series of questions to download and install it.
Instead, Zaurus users have to decide whether the software is compatible and whether there is room to install it, as well as where, and how the software is going to be installed.
This is partly due to the Zaurus' limited space, as well as decisions made by developers about how much troubleshooting in package installation to automate.
While you can click on a filename or icon to install an application, you have to know how to find the icon or filename to do that,
and where you look depends on whether the package is on your Zaurus or on a package feed.
In order for an application to be installed to your Zaurus,
a copy of the application's installation package, whether it is an IPK, a tgz file, a zip file, or
has to be somewhere that your installation software can easily access the package or file.
If the package is not already on your Zaurus, your desktop, a CD or expansion card, then you have the option of installing it directly from a Package Feed on the Internet,
or of simply downloading the package and installing it later as a separate step.
If you want to install the package directly from a feed using your Installer, skip to the next section.
There are many ways to download IPKs to the Zaurus:
Using your browser
This is the simplest, most straightforward
way to download an IPK. Simply click on the link
to the IPK in your browser, and answer the questions
about where you want to install it.
If you have problems with the binary appearing on
your screen instead of downloading as a file, this
is probably a problem with mime-type declaration at the website
involved and you should contact the administrator
to get them to correct the problem. Meanwhile,
use a different method for downloading.
Software residing on an ftp site can be downloaded with your browser, with an FTP client, or with command line ftp.
If you have ssh set up on both your Zaurus and a host computer or server, you can download IPKs to your Zaurus using scp.
Before attempting installation, you must make sure the package is of the correct format for your particular ROM. If you are not sure, then I recommend downloading the IPK and examining it
first, if you want to avoid serious problems. Please read the previous section about downloading, and be sure to also read the section below about formats.
From what I have found so far, it sounds like you go online, open up the built-in software installer, and type in the url of the
package or of the feed you want to download something from.
For more details, sl5xxx Sharp ROM users can consult their operations manuals. For ROM 2.38, the manuals are
I understand the procedure for pdaX ROM users, which I gleaned from Capn_Fish's writeup for a pdaXrom user,
which you could formerly read in the tyrannozaurus archive (see NOTE below),
by modifying the following URL to contain /old2/ instead
of the slash between ".com" and "?q":
The procedure is to
go to the setup.
type in the URL for a feed,
reload the lists,
go to the "available" tab
select packages to install
Click the gear to download and
Here are some more resources describing the Package Feed Method:
Your package may install without a problem, or you
may be able to resolve simple installation problems
without a console. However, I highly recommend that
you install a console if you do not have one, so
that you can use it to help in resolving any problems
The tyrannozaurus wiki page for adding/retrieving information about consoles for the Zaurus
was at http://www.tyrannozaurus.com/?q=wiki/Available_Consoles, and an archived copy is now available at:
Install a GUI file manager if you do not have
one, unless you feel comfortable examining your
file system from the command line.
wiki pages on file managers for the Zaurus seem to still be in the fledgeling state, so here
is a bit more info as well. ;)
qpe-terminal works on early Sharp/Cacko ROMs and Tree!Explorer has been said to be the very best File Manager: http://hpcgi2.nifty.com/taku2001/zau/texplorerqt/top_en.cgi It definitely works for one tyrannozaurus member who has an sl-5500. However, the official home page says, "No guarantee for SL-A300,
SL-B500 or SL-5500."
Midnight Commander is another possibility
Here are the Zaurus file manager wiki pages I know of (as I said above, in the fledgeling state)
(see NOTE below about Tyrannozaurus wiki
Available File Managers | tyrannozaurus.com http://web.archive.org/web/20071028083412/http://www.tyrannozaurus.com/?q=wiki/Available_File_Managers
Note: Visitors formerly needed to sign in as a user to view the tyrannozaurus file manager wiki page. When I tried viewing it while logged out, I got no content, and there definitely was some, so this page is not likely to be at Archive.org, but only available in private archives. However, I did find a copy at archive.org, as indicated above! Again, see NOTE below about Tyrannozaurus archives.
Make sure the ipk is not corrupt by running the md5sum command:
A proper feed will have a packages page that lists the "md5sum" value for each program. If the md5sum you get when your run md5sum is the same as is on the feed, then you should be okay, assuming that the feed contains a non-corrupt package.
Make sure the format is correct for your ROM. This is absolutely essential. If you attempt to install an IPK which is meant for a different type of ROM, it can cause very serious problems, sometimes erasing or overwriting
directories inappropriately, and cause your Zaurus to crash. Just because a file has a ".ipk" as it is file type, does not make it safe to install on your Zaurus. You must make sure the IPK you are interested in has been compiled to be compatible with your model and ROM.
The best way to do this is to get your ipks from a feed which only features packages for your type of ROM.
However, that is not
If you have a pdaXrom,
you need ipks ending with "armv5tel.ipk".
If you are a Sharp, Cacko, or Opie ROM user,
here is a summary of the information I found in the superb thread on this topic at oesf, on how to tell whether an ipk is a "Sharp" vs. an "Opie" ipk:
If your ipk will not install, you can tell whether it is an opie-compatible or a Sharp/Cacko compatible ipk by examining the first few bytes.
Miami_Bob suggests using Midnight Commander or a hex editor, but I find I achieve similar results by viewing it with the "od" command.
"The Sharp "flavor" IPKs all start
with (hex) 1F 8B 08 - followed by
either (Hex) 00 or 08.
The OPIE "flavor" all start with
(Hex) 21 3C 61 72 63 68 3E 0A [ ACSII
= !<ARCH> ]."
You can examine the files with a hex editor, but it is easier to examine with the "od" (octal dump) command.
The following will also yield the desired information:
od -N 16 -t x1 yourname_arm.ipk
The "od" command is not built in to most Zaurus ROMs at this point, but it can be extracted or installed, from the arm utilities package, available at:
To save yourself a lot of grief, you also should try to ensure, before installation,
that you have all the libraries and modules required by the application.
A proper package feed should have a Packages file, which should list the dependencies. http://elsix.org also attempts to check dependencies for packages, although I do not know how reliable it is in this realm.
If you have already installed the package, and find it will not run, you can use the "ldd" command to check the dependencies. See this page about "ldd".
If you try installing and the installer complains that there are missing libraries,
you may have a version of the application that was
not compiled for your particular ROM, or the package
was not put together to make installation user-friendly.
But sometimes although an application looks like it is going
to run, it does not "raise",
nothing seems to happen. So,
whether or not ipkg complains about missing libraries,
it is probably not a bad idea to run the
"ldd" command to make sure that all
dependencies are satisfied. My writeup about "ldd" is at
In some instances, the program expects a specific
version of a library, and you have a different one.
As shown below, you can try symlinking to whatever version of a
missing library you have, to see if that works.
Sometimes it will suffice, and sometimes you will
need to install the specific version required by
First, to see what libraries you already have on your Zaurus
to consider symlinking to, run a "find"
command to hunt for similar libraries.
On some ROMs, you also have the option of running
the ldconfig command. Entering
"ldconfig -v" will tell you what libraries are already
recognized by your system.
Sometimes a library has been installed without universal read permission, and this will be a problem for ROMs where you are not running as USER=root.
You can tell this because entering "ldconfig -v" will show the library in question as "not found",
but it will be found, for those who have sudo installed,
if you enter "sudo ldconfig -v".
To correct this problem, you will need to locate the library using the "find" command, and
then grant read permission using "sudo chmod +r LIBRARYNAME". I
expect to add more detail, along with examples of this. Until then, though
I wanted to at least mention it, as it can wreak havoc when you think a library is there but it is not recognized.
Now, please note that on some ROMs, you may have problems
following the procedure described below for
installing libraries by hand, because of write permissions. I will try to
include more on this when I can. Meanwhile, check the forums and feeds for sudo.
As an example of using the find command to do this, let's say that I want to see what I have in the way of
libstdc++ libraries, I would run the following:
bash-2.05# find / -name "libstdc++*" | xargs ls -l
find: /proc/12/fd: No such file or directory
lrwxrwxrwx 1 root root 50 Aug 17 2006 /home/root/usr/lib/libstdc++-3-libc6.1-2-2.10.0.so -> /mnt/card/Programs/libstdc++-3-libc6.1-2-2.10.0.so
lrwxrwxrwx 1 root root 31 Aug 16 2006 /home/root/usr/lib/libstdc++-libc6.1-2.so.3 -> libstdc++-3-libc6.1-2-2.10.0.so
-rwxr-xr-x 1 root root 1229996 Sep 4 2003 /usr/mnt.rom/card/Programs/libstdc++-3-libc6.1-2-2.10.0.so
In the above example, I can tell from the arrows that I already have two symlinks to libstdc++-3-libc6.1-2-2.10.0.so. If my application wants a library called
libstdc++-3-libc6.1-2-3.10.0.so, I could make a symlink for it as follows:
We then can check our new symlink with the "type" command. If the symlink worked, your output will look something like the following:
bash-2.05# type /home/root/usr/lib/libstdc++-libc6.1-2.so.3
And if the symlink was not done properly, the output will look something like the following:
bash-2.05# type /home/root/usr/lib/libstdc++-libc6.1-3.so.3
bash: type: /home/root/usr/lib/libstdc++-libc6.1-3.so.3: not found
Then, once we have a working symlink or have installed the desired library,
we can try installing or running our application again.
If the procedure outlined here works, great! If it does not work, you will need to find a version of the required library
that is compatible with both the application and your ROM.
Where to locate copies of required libraries
depends on your architecture. You can try the package feed for your particular ROM. I usually just
ask someone who knows my particular
ROM where I can get a compatible
version of any missing libraries that may be required.
I also try googling, for example, for my Collie running ROM 2.38, "MYLIBNAME 2.38 ipk" or "MYLIBNAME collie ipk".
For an sl3000 running pdaXrom, I would search for either
"YOURLIBNAME pdaXrom ipk" or "YOURLIBNAME sl3000 ipk".
Finding or starting a thread at oesf Software forum, or at a forum for your ROM,
and asking who has a compatible version of
the library or libraries, might be helpful if you fail to find it or them yourself.
Make sure the media you are installing it on has no bad spots.
To do this, first, check the type of file system on your media with the "mount" command. To avoid misleading results, do not give any arguments. If you want to limit the output to one particular device, then pipe the output through grep.
/dev/mtdblock0 on / type cramfs (ro)
/proc on /proc type proc (rw)
/dev/ram1 on /dev type minix (rw)
/dev/mtdblock1 on /home type ext2 (rw,sync) none on /dev/pts type devpts (rw)
/dev/mmcda1 on /usr/mnt.rom/card type vfat (rw)
Then unmount the card with the "umount" command (note there is no "un" in the command), and run the appropriate version of fsck to check the file system. This will also reveal any physical bad spots on the media.
If you do not know how to type a pipe
on the sl5500's hardware keyboard, you can type
pipe by simultaneously pressing the
space key and the
up arrow key (which is on the left side of your
above the function (Fn) key).
To run fsck on an ext2 SD card, run the following command sequence:
bash-2.05# umount /mnt/card
bash-2.05# fsck.ext2 -v -t -a /dev/mmcda1
And for an ext2 formatted CF card:
bash-2.05# umount /mnt/cf
bash-2.05# fsck.ext2 -v -t -a /dev/hda1
Unfortunately, Sharp's version of fsck.vfat is not reliable, at least not on ROM 2.38, but you can try to run it for an SD card as follows:
bash-2.05# umount /mnt/card
bash-2.05# fsck.vfat -v -t -a /dev/mmcda1
And for a CF card, the command would be:
bash-2.05# umount /mnt/cf
bash-2.05# fsck.vfat -v -t -a /dev/hda1
For an in-depth discussion about checking expansion
card integrity, with more examples as well as resources on this topic, see
Always make a backup before installing new software.
Sometimes something serious can go wrong with package
installation, and an up-to-date backup can enable you to easily
restore your system with a minimum of data loss.
--need to show how to examine the ipk for how much space is required
Before attempting installation to internal memory, make sure you have at least twice the amount of space required for the software, in internal memory. If you are installing to an SD or a CF card, there still must be enough room in internal memory for ipkg to unpack the ipk before putting the files into place on the expansion card.
If you are unable to clear enough space in internal memory, then consider unpacking and installing by hand.
(this requires detail about how to do it)
(I can try to write this one up when I have the time)
To debug any serious problems with installing IPKs, you must either start the built-in GUI installer from the command line, or run ipkg yourself.
Here are the ways to start installation from command line:
To use Sharp/Cacko GUI, the following will start the Add/Remove Software application,
but on some ROMs, it will still not allow you to capture any error messages in your terminal.
If you need to see them, you may have to use ipkg instead of qinstall:
To use the OpenZaurus GUI:
Not recommended, because the GUI
installer crashes, Meanie recommends OZ people use the command line version instead (see below)
To use pdaX ROM GUI:
--what are GUI installer names for other distros?
To install from command line using ipkg (all ROMs) without calling the GUI:
If you are having problems with installation, your
ability to get assistance from others, whether in chat, in
the forums, or on mailing lists, it will be extremely
helpful if you
provide a copy of the output to others, so they
can more effectively assist you.
So, when the error message appears in your GUI, or ipkg is done, copy and paste everything that has appeared on the screen, including the command you entered, into a file. Be sure to save the file before you close the GUI installer.
If you cannot connect to the Internet with your Zaurus to post the output, try sending the file to your laptop or desktop. If you do not have one, consider getting an SD or CF card reader for the laptop
as another way to transfer information to it from your Zaurus, which you then could post at the forums.
If you are using the GUI installer, exit from it (should people tap OK or EXIT? It should not matter, but some GUI applications handle "OK" and "EXIT" differently, and if you are having problems, this may be another factor to pay attention to.)
If you find that the package you want to install is not recognized
you should double check and make sure that you have read and followed the instructions in the above sections on finding a compatible IPK, on confirming the integrity of the ipk, and on verifying that the IPK is of the correct format for your distribution.
If the format is correct, the IPK is compatible with your model, and the IPK is intact, then often the problem is due to ipkg not liking the filename for some reason.
If you prefer using the GUI installer, you may be able to get the IPK to be seen in the GUI by following these instructions for starting the GUI from the command line. Just make sure you enter the full path to the IPK on the command line.
Another trick to try is to rename the file. ipkg does not like to install files with underscores in their names. Simply rename the file with the "mv" command, changing the underscores to hyphens, and see if that works.
If the above tricks do not work, you may have to try installing the ipk completely from the command line, following the instructions given here.
If you have started your GUI installer from the command line, in some cases, you may see the dreaded "bad tar header" error messages. For some reason, tar sometimes complains despite proper file installation. So, before you assume that your ipk is corrupt, follow the steps below to check installation and restart your system, as there may be nothing wrong.
If checking installation and restarting your system fail, then try unpacking the IPK by hand. I have had instances where one or two essential files did not unpack properly due to a bad tar header when I installed the application using my GUI, but was able to retrieve uncorrupted versions of the files by unpacking the IPK by hand. Check out the detailed example of how to unpack an IPK by hand on my tiffviewer page.
You can confirm that you have installed an ipk
correctly in at least two or three ways.
If the GUI installer says "Installation failed" or "something went wrong", before you assume the ipk did not install, try to run the program because it might run anyhow.
Besides just trying to run it, you also can use the bash "type" command. In my case,
for example, I have installed Opera, but I do not have kismet
bash-2.05# type opera
opera is /home/QtPalmtop/bin/opera
bash-2.05# type kismet
bash: type: kismet: not found
If you have installed the ipk, you also can use the "ipkg status" command. In my case:
bash-2.05# ipkg status opera
Status: install ok installed
bash-2.05# ipkg status kismet
There is no output from "ipkg status" because Kismet had not been installed with either ipkg or the GUI installer on my Zaurus.
Note that ipkg will not detect the presence of a package installed some other way. For example, I installed efax by hand, instead of using ipkg or the GUI. So, ipkg does not show it to have been installed, but bash recognizes it as an executable, and it definitely sends faxes for me.
bash-2.05# ipkg status efax
bash-2.05# type efax
efax is /home/QtPalmtop/bin/efax
If there is no icon in the Applications menu, you have a few choices:
First, try just rebooting or doing a soft reset. Sometimes that is all it takes for the system to find and display the icon. But first read the warnings below.
You can run the application from the command line. You can do this by simply entering the
name of the executable on the commandline.
If the executable is not on your $PATH, then you will need to give the full pathname.
The problem with doing this without also making a desktop entry is that there will be no icon for the application in the taskbar.
If you are lucky, you can find the name by running "ipkg status" from the command line. However, this
is not always a reliable way to find the name of an executable. For example, my console has the package name "qpe-terminal",
but the executable is called "embeddedkonsole".
However, you can use the Package name as shown in the output of "ipkg status" to hunt for the
ipkg list and locations of files used by the application. Try the following:
find / -name your-package-name.list
As an example, tkcMail's Package name from ipkg status is "tkcmail." So, I can look for the listing as follows:
You can try to locate all binary, image and desktop files and move them to the appropriate directories. See the above explanation of how to do this.
On Sharp ROMs, the image files usually go into /home/QtPalmtop/pics/, the desktop entries go into /home/QtPalmtop/apps/Applications/, and the
binary itself can go into any directory named when you do "echo $PATH".
On my Sharp ROM, /home/QtPalmtop/bin/ is a good location.
On pdaX ROMS,
the executables usually go into /usr/bin or
/usr/local/bin, and sometimes can be found in /sbin, /usr/sbin, or /usr/local/sbin.
pdaXrom image files belong in /usr/share/pixmaps or
And pdaX ROM .desktop files should be placed in /usr/share/applications or
--need more detail for other ROMs here.
You may need to make your own desktop entry.
I did this when I decided to install an alternate version of Opera by just putting the binary into my path, without using ipkg or qinstall to do the installation.
Here is an example of a minimal desktop entry:
Comment=A HTML Editor for the Z
The "Exec" entry is the precise binary name. The "Icon" entry requires the name of the icon used for the taskbar and Applications Tab.
The "Name" entry is the name of the application that you want to appear below the image in the Applications Tab.
Note that if you make your own desktop entry, you will have to restart Qtopia (or reboot if you do not have a Qtopia based ROM)
to have it take effect.
In my case, I copied the desktop entry for Opera 7.30 to make a desktop entry for Opera 6.0.
I then edited opera6.desktop so that it called Opera 6 instead of Opera 7.30. Then I restarted Qtopia using the "Shutdown" application in the Tools tab. And now I have two icons for Opera, one labeled as
"Opera 6 Browser" and the other labeled "Opera 7.30 Browser".
And I definitely get an icon when I run Opera 6, whether I use the GUI or the command line to start it.
In some cases, you may also need to add a "File" line to your desktop file which specifies the precise location of your application. Here is an example:
In some cases, the icon will display in the Applications Menu, but there is no icon in the taskbar, even though there is a properly written desktop entry. I have quite a few applications in which this is the case, and have not yet figured out how to resolve the issue. If you know how, please PM me at oesf, thanks.
Sometimes the program files have been unpacked, but they have been placed in a directory which is not in your path.
See the above discussion in the missing icons section,
for information about how to locate the unpacked binaries for your application.
Then, to find out where scripts and commands must be placed on your Zaurus so that it can find them, examine your $PATH variable:
bash-2.05# echo $PATH
If the program files are not in one of these directories, they need to be moved there. Sometimes they are in an unrecognized directory because the IPK was written for a different ROM, and sometimes they are in the wrong directory because the installer crashes before completing installation.
The software that installs IPKs extracts the files to a temporary directory, and you may be able to retrieve them from there and put them into place.
So, if the program does not run, you can examine the
contents of the temporary ipkg installation directory for the files.
In general, you can find out which directory to examine by doing "cat /etc/ipkg.conf".
Here are some likely locations:
In some cases, even though you have followed all of the above steps, even when the package seems to have installed properly,
there are glitches. There are missing icons, or entering data or clicking on buttons or menu items does not seem to have any effect or to work properly.
Before you conclude that the package does not, can not and will not work on your Zaurus, considering restarting your operating system.
Before you do this, make sure that you make backup copies on another media of any important data files that you may not have copies of on a recent system backup.
This is because if something serious has gone wrong, while everything may be fine, there is always the risk when restarting the system, of a major crash of your Zaurus, with total loss of data.
NOTE: The Tyrannozaurus Forum has been taken down, but archival copies of the forum are available from Antikx, and most or all pages are also archived at archive.org. Note the feeds at Tyrannozaurus are still there, it is just the TY Forum that has been removed. I am researching the URLs of the Forum pages referred to above, many or all of which are available from the Wayback machine at http://web.archive.org, and will post hot links to the pages referred to above when I can.
Meanwhile, feel free to PM me or Antikx at http://oesf.org if you need assistance and are not able to find caches of the pages at http://web.archive.org.