Page Contents


Feature List

Previous topic

OMERO.server installation

Next topic

OMERO.server Linux walkthrough

This Page


This documentation is for the new OMERO 5.2 version. See the latest OMERO 5.1.x version or the previous versions page to find documentation for the OMERO version you are using if you have not upgraded yet.

OMERO.server Mac OS X installation walk-through with Homebrew


This walk-through demonstrates how to install OMERO on a clean Mac OS X system (10.8 or later) using Homebrew. Note that this demonstrates how to install OMERO.server from the source code via Homebrew, in addition to all its prerequisites. The default instructions for UNIX platforms in the OMERO.server installation guide are all you need to install the prerequisites with Homebrew and then install the server zip from the downloads page or build from source.

These instructions are implemented in a series of automated scripts which install OMERO via Homebrew from a fresh configuration.



Homebrew requires the latest version of Xcode.

  • Install Xcode from the App Store; if you have already installed it, make sure all the latest updates are installed

  • Run the following command to install the command-line tools for Xcode:

    xcode-select --install


Oracle Java may be downloaded from the Oracle website.

After installing JDK 7 or JDK 8, check your installation works by running:

$ java -version
java version "1.8.0_31"
Java(TM) SE Runtime Environment (build 1.8.0_31-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.31-b07, mixed mode)

$ javac -version
javac 1.8.0_31


Follow the installation instructions on the Homebrew wiki. All the requirements for OMERO will be installed under /usr/local.

$ ruby -e "$(curl -fsSL"
$ brew install git

The installation of OMERO via Homebrew depends upon two alternate repositories containing extra formulae: for the HDF5 formula and for all the OME-provided formulae and older versions of Ice. To add these, run:

$ brew tap homebrew/science
$ brew tap ome/alt

Lastly, make sure /usr/local/bin is before /usr/bin in your PATH. For example, add the following to ~/.profile and then start a new shell for the change to take effect:

export PATH=/usr/local/bin:/usr/local/sbin:$PATH

Python 2.7

You can install OMERO using either the Python 2.7 provided by Homebrew, or the system-wide Python 2.7 provided by MacOS X. Homebrew Python is recommended since it makes using Homebrew-provided modules simpler, for example the Ice python bindings needed by OMERO. For a more thorough description of the Homebrew solution, see the Homebrew and Python page. Note that the automated script linked above tests the OMERO installation using the Homebrew Python.

To install the Python provided by Homebrew:

$ brew install python

Check that Python is working and is version 2.7:

$ /usr/local/bin/python --version
Python 2.7.9

If using system Python, add the following to ~/.profile and then start a new shell for the change to take effect:

export PYTHONPATH=$(brew --prefix omero)/lib/python

If using Homebrew Python, this will be on the default module path.


If you have a local .bash_profile file, it will override your .profile configuration file.

Independently of the chosen Python, you can set up and use virtual environments to install the OMERO Python dependencies (see Python dependencies).


The Homebrew formulae used below provide Python bindings. As described in Homebrew and Python, you should not be in an active virtual environment when you brew install them.

OMERO installation

OMERO 5.2.0

To install and deploy the 5.2.0 release of OMERO.server, run:

$ brew install omero

This should install OMERO along with most of the non-Python requirements.

Additional installation options can be listed using the info command:

$ brew info omero

The default version of Ice installed by the OMERO formula is currently Ice 3.5.

Development server

If you wish to build OMERO.server from source for development purposes, using the git repository, first use Homebrew to install the OMERO dependencies:

$ brew install --only-dependencies omero

The default version of Ice installed by the OMERO formula is currently Ice 3.5.

Prepare a place for your OMERO code to live, e.g.

$ mkdir -p ~/code/projects/OMERO
$ cd ~/code/projects/OMERO

If you installed Ice 3.5, you will need to set SLICEPATH to be able to build the server, i.e. export SLICEPATH=/usr/local/share/Ice-3.5/slice.

If you want the development version of OMERO.server, you can clone the source code from the project’s GitHub account to build locally:

$ git clone --recursive git://
$ cd openmicroscopy && ./


If you have a GitHub account and you plan to develop code for OMERO, you should make a fork into your own account and then clone this fork to your local development machine, e.g.

$ git clone --recursive git://
$ cd openmicroscopy && ./

See also

Installing OMERO from source
Developer documentation page on how to check out to source code
Build System
Developer documentation page on how to build the OMERO.server

Additional OMERO requirements


Install PostgreSQL:

$ brew install postgresql
$ postgres --version
postgres (PostgreSQL) 9.4.1

Python dependencies

The Python dependencies can be installed in the system-wide Python site-packages, in the Homebrew Python site-packages or within a virtual environment. If you are using the system-wide Python site-packages, you may need to use sudo to install the dependencies. If you are using a virtual environment, activate it before calling the Python dependencies installation script.

If you installed OMERO using Homebrew, execute the omero_python_deps script:

$ omero_python_deps

If you use a development server, execute the script under docs/install:

$ cd ~/code/projects/OMERO
$ docs/install/

If you encounter problems with the installation script, please take a look at Common issues.


Database creation

  1. Create a new database cluster:

    $ initdb -E UTF8 /usr/local/var/postgres
  2. Start the PostgreSQL server.

    If you wish to use brew services to start postgresql, you will first need to install it, then start the service:

    $ brew tap gapple/services
    $ brew services start postgresql

    Alternatively, to start by hand:

    $ pg_ctl -D /usr/local/var/postgres/ -l /usr/local/var/postgres/server.log start

    It is also possible to configure launchd to start PostgreSQL at boot

  3. Create a user and database:

    $ createuser -P -D -R -S db_user
    Enter password for new role:       # enter db_password
    Enter it again:                    # enter db_password
    $ createdb -E UTF8 -O db_user omero_database

    Note db_user and db_password should be replaced with a username and password of your choice. Record these for future use.

  4. Check to make sure the database has been created.

$ psql -h localhost -U db_user -l

This command should give similar output to the following:

                        List of databases

   Name         | Owner   | Encoding |  Collation  |    Ctype    | Access privileges
 omero_database | db_user | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 |
 postgres       | ome     | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 |
 template0      | ome     | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 | =c/ome           +
                |         |          |             |             | ome=CTc/ome
 template1      | ome     | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 | =c/ome           +
                |         |          |             |             | ome=CTc/ome
(4 rows)


Now configure OMERO.server to connect to the newly-created database:

$ omero config set omero_database
$ omero config set omero.db.user db_user
$ omero config set omero.db.pass db_password

And then, generate the database schema:

$ omero db script --password secretpassword

You should see output similar to this:

Using OMERO5.2 for version
Using 0 for patch
Using password from commandline
Saving to /home/omero/OMERO5.2__0.sql

Then run the SQL commands in the generated schema file to create the database:

$ psql -h localhost -U db_user omero_database < OMERO5.2__0.sql

Now create a location to store OMERO data, for example:

$ mkdir -p ~/var/

and configure OMERO.server to use this location:

$ omero config set ~/var/

The OMERO.server configuration settings can be inspected using:

$ omero config get

Next, start the OMERO.server:

$ omero admin start

Now connect to your OMERO.server using OMERO.insight with the following credentials:

U: root
P: root_password


In order to deploy OMERO.web in a production environment such as Apache or Nginx please follow the instructions under OMERO.web deployment.


The internal Django webserver can be used for evaluation and development. In this case please follow the instructions under OMERO.web deployment for developers.

Common issues

General considerations

If you run into problems with Homebrew, you can always run:

$ brew update
$ brew doctor

Also, please check the Homebrew Bug Fixing Checklist.

Below is a non-exhaustive list of errors/warnings specific to the OMERO installation. Some if not all of them could possibly be avoided by removing any previous OMERO installation artifacts from your system.


Warning: It appears you have MacPorts or Fink installed.

Follow uninstall instructions from the Macports guide.


If you encounter this error during installation of PostgreSQL:

Error: You must ``brew link ossp-uuid' before postgresql can be installed


$ brew cleanup
$ brew link ossp-uuid


If you encounter an MD5 mismatch error similar to this:

==> Installing hdf5 dependency: szip
==> Downloading
Already downloaded: /Library/Caches/Homebrew/szip-2.1.tar.gz
Error: MD5 mismatch
Expected: 902f831bcefb69c6b635374424acbead
Got: 0d6a55bb7787f9ff8b9d608f23ef5be0
Archive: /Library/Caches/Homebrew/szip-2.1.tar.gz
(To retry an incomplete download, remove the file above.)

then manually remove the archived version located under /Library/Caches/Homebrew, since the maintainer may have updated the file.

numexpr (and other Python packages)

If you encounter an issue related to numexpr complaining about NumPy having too low a version number, verify that you have not previously installed any Python packages using pip. In the case where pip has been installed before Homebrew, uninstall it:

$ sudo pip uninstall pip

and then try running again. That should install pip via Homebrew and put the Python packages in correct locations.