Migration from OMERO 5.5 (Python 2) to OMERO 5.6 (Python 3)

This page serves as a collection of recommendations, developed as the OME team went through the migration to Python 3. This is not a complete guide but may serve as a useful starting point.

For more information, please see a dedicated Python 3 page like http://python-future.org/.


Installing future from Python 3 is now required for all OMERO Python components. This library comes with the futurize tool which performs many of the basic transformations needed to migrate Python 2 code to Python 3:

futurize -0 your_file.py

Add -w to update the file in place.


The most common transformation needed is adding parentheses around print statements since print is no longer a keyword.


The return value from the keys() method of dictionaries is of type dict_keys and no longer has methods like sort(). Wrap with a call to list if you need the previous behavior: list(my_dict.keys()).


Changes to the handling of strings was our major hurdle in upgrading from Python 2 to Python 3. In Python 2, there is a separation between str and unicode. In Python 3, both of those are like unicode (but called str) and a new type was introduced: bytes. A good starting places to learn the difference is:


The future library which enables support for Python 2 and Python 3 concurrently has its own str class. It is necessary to look at the imports for a module to know what str is being used.

Which str is it??

If nothing special is imported, str is the builtin str which in Python 2 is non-unicode and unicode in Python 3. String literals like “foo” are also of type str.

If unicode_literal is imported, then “foo” is the same as u”foo” and is unicode in Python 2 or just str in Python 3.

If from builtins import str is imported, then str is more like unicode and may fail existing calls to isinstance().

isinstance(x, str)

Since str can change its type, this often will not do what you want. Using past.builtins.basestring is generally a good solution, e.g. isinstance(x, basestring)


If you are trying to turn a variable into a string, this may not do what you want since it might be creating a unicode.

This is especially problematic for passing strings to Ice methods, which are implemented in C++ and fail spectacularly if they receive non-string objects (like unicode).

future.utils.native_str maintains the previous semantics producing builtin str objects. Native str semantics are especially important when working with Ice, e.g.

ctx = {'omero.group': native_str(groupId)}
conn.getUpdateService().saveArray(pixels, ctx)

StringIO and open(“file”, “r”)

StringIO and open() may need replacing with BytesIO and open(“file”, “rb”) respectively. This depends on whether or not your code is expecting a stream to be binary.


Regexes must start with r”” for raw to prevent escapes from being misinterpreted (e.g. d).


long no longer exists. Replace omero.rtypes.wrap(long_value) with omero.rtypes.rlong(long_value).

Division with / now produces a floating point. For example, choice * int(percent) / 100 no longer produces an integer in Python 3. Use //.