Migrating to Nautilus API 4.0: nautilus-python Reference Manual

# Migrating to Nautilus API 4.0

Nautilus 43 no longer allows extensions to directly manipulate GTK widgets – all UI changes now need to happen through model objects. If your script implements any of the following provider interfaces, you will need to update it:

## LocationWidgetProvider

The `Nautilus.LocationWidgetProvider` was removed without replacement. If your script requires it, you can request a new model-based API for your specific use case on the Nautilus issue tracker.

## MenuProvider

The `get_file_items`, `get_file_items_full`, `get_background_items` a `get_background_items_full` methods of `Nautilus.MenuProvider` no longer take the `window` argument. Remove it from your implementations.

If you need to keep supporting older versions of Nautilus, you can use variadic arguments:

    1
    2
    3
    4
    def get_file_items(self, *args):
        # `args` will be `[files: List[Nautilus.FileInfo]]` in Nautilus 4.0 API,
        # and `[window: Gtk.Widget, files: List[Nautilus.FileInfo]]` in Nautilus 3.0 API.
        files = args[-1]

## PropertyPageProvider

The `Nautilus.PropertyPageProvider` was replaced by `Nautilus.PropertiesModelProvider` class. Unlike the previous unrestricted property pages that could contain any GTK widget, the new model-based interface currently only supports a pre-defined layout. Scripts can add pages, each of which can display a list of text properties.

Subclass the `Nautilus.PropertiesModelProvider` abstract class and have the `get_models` method return the list of `Nautilus.PropertiesModel`, one for each properties page.

If you need to keep supporting older versions of Nautilus, you can keep the old definition conditionally:

    1
    2
    3
    4
    5
    6
    7
    if hasattr(Nautilus, "PropertiesModelProvider"):
        # For Nautilus 4.0 API
        class MD5SumPropertiesModel(GObject.GObject, Nautilus.PropertiesModelProvider):
            ...
    else:
        class MD5SumPropertyPage(GObject.GObject, Nautilus.PropertyPageProvider):
            ...

## Direct use of GTK and other libraries

If you use GTK directly, e.g. to create dialogue windows, you will need to upgrade the code to GTK 4 as well, since Nautilus switched to GTK 4 and it is not possible to use multiple versions of GTK in the same process. Do not forget to replace `gi.require_version("Gtk", "3.0")` with `gi.require_version("Gtk", "4.0")`, then.

The other option is moving the window and dialogues into a separate program and having the extension just launch it. But unless the code base is very large, migrating to GTK 4 will probably be easier.

## More information

See the relevant Nautilus change for more context and the corresponding nautilus-python update for more migration examples.