GNOME Files (nautilus): the file manager you extend, not the one you replace

What GNOME Files solves, and who the nautilus repository is actually for

The nautilus repository is the source of the Files app, the file browser that ships as part of the GNOME desktop. The README is explicit that this is a core component of the GNOME experience, not a standalone utility with its own release cadence. That framing matters more than it first appears: it means the project is not trying to be a universal file manager for every Linux desktop, and it is not trying to win users away from anything. It exists to give GNOME a file browser that matches the desktop's design language and integrates with the rest of the stack.

The audience follows from that. If you are a GNOME user, you are already running this. If you are a distribution packager, you are building it. If you are a developer who wants to add a context menu entry, a property page, or a column to the file list, the repository is where the extension API lives. The README points extension authors at the libnautilus-extension documentation and, for Python, at nautilus-python. That is the practical entry point for most people who arrive here deliberately rather than by package dependency.

Runtime dependencies shape what the file browser can do

Three runtime dependencies are listed, and each one maps to a visible capability. Bubblewrap is described as installed for security reasons, which is consistent with how GNOME sandboxes parts of its application stack. LocalSearch is the more interesting one: the README says it is used for fast search and metadata extraction, starred files, and batch renaming. So three features that a user might assume are built into the file browser are in fact delegated to a separate service. If LocalSearch is not properly set up, or is built without all features enabled, those functions degrade or disappear. The README's phrasing, "properly set up and with all features enabled," is a warning worth taking literally.

The third dependency, xdg-user-dirs-gtk, handles default bookmarks and localization updates. This is a smaller piece, but it explains why the sidebar bookmarks can look wrong on a system where the XDG user directories were never initialised. None of these are optional in the sense of being trivially absent; they are part of the supported configuration.

Getting nautilus and the supported way to reproduce a problem

The README does not include build instructions, so there is no configure or compile command to quote here. What it does give is a support path. Only the latest version of Files as provided upstream is supported, and the project asks you to try the Flatpak nightly installation before filling issues, so that the installation is reproducible and free of downstream changes. The README links to the installing-a-nightly-build page under welcome.gnome.org for that.

If the problem cannot be reproduced in the nightly installation, the README says to file an issue in your distribution instead, so that the issue is well triaged and reaches the proper people. That is the whole of the documented workflow, and it is worth following in order: nightly first, distribution second, upstream issue tracker only when the nightly reproduces the fault.

For extensions, the entry point is different. The README links to documentation for the libnautilus-extension API, and separately to the nautilus-python documentation for anyone writing a Nautilus extension in Python. There is no install command for either in the README; the API documentation is the starting point it names.

The extension API is the reason to build it yourself

Most people who compile nautilus do so to write an extension. The libnautilus-extension directory holds the public API, and the README links to generated documentation for it. Python developers get a separate path through nautilus-python, which the README also links. The split is deliberate: the C API is the native surface, and nautilus-python is a binding layer maintained alongside it.

What the README does not say is how stable that API is between releases. There is no compatibility promise in the text, and no versioning policy for extensions. If you are planning to ship an extension to users, that silence is the thing to investigate before you commit, because a C API that shifts with the desktop release cycle imposes a maintenance cost on every downstream extension author. This is a real trade-off of the project being a core component: it optimises for the desktop, not for third-party ABI stability.

Feature requests go through design review, not the issue tracker

The README is unusually direct about this. Changes in behaviour or appearance happen in accordance with the GNOME design team. For major changes, the guidance is to start on Discourse, reach out in the GNOME design Matrix room, and only involve the issue tracker once agreement has been reached. Mockups must be approved by the design team to be considered for implementation. Smaller, well-defined enhancements can go straight to an issue using the shortcoming template.

This is the single biggest practical difference between nautilus and a typical open source application. A pull request that adds a feature nobody asked for will be closed, not because the code is bad, but because the feature was never agreed. If your workflow depends on a particular behaviour and you intend to change it upstream, budget time for the discussion before you write code. If you only need the change for yourself, an extension is the shorter path, and it does not require anyone's approval.

When nautilus is the wrong tool

Two cases stand out. The first is anything that is not GNOME. The README describes Files as a core component of the GNOME desktop experience, and the design review process reinforces that. Running it under a different desktop is possible, but you inherit a component that is tuned for a desktop you are not using, and the project is not oriented toward your needs.

The second is a workflow that depends on features LocalSearch provides. Because fast search, metadata extraction, starred files, and batch renaming all route through that service, a system where LocalSearch is absent or built without all features enabled gives you a file browser missing functions you may have assumed were intrinsic. The README treats this as a setup requirement, and it is the first thing to check when one of those features misbehaves.

A third, softer case: if you need a file manager with a stable plugin ABI that survives desktop upgrades, the absence of any compatibility statement in the README is a caution rather than a promise.

Licence and the cost of tracking upstream

The repository is licensed GPL-3.0, with the licence file at the top level. For extension authors this is the detail that decides how you can distribute your work: linking against libnautilus-extension brings the usual GPL considerations, and if you are shipping a proprietary extension you need to look at that carefully rather than take a summary from an article. This is not legal advice; read the licence text.

Upgrade cost is dominated by the support policy. Only the latest upstream version is supported, and the recommended triage path runs through the Flatpak nightly. If you package nautilus for a distribution and carry patches, you are on your own for support, which the README states plainly. For extension authors, the cost is the API surface: every GNOME release is a chance that something you depend on has moved, and there is no published stability guarantee to plan around.

Alternatives and how they differ

The obvious comparison is with the file managers built for other desktops, such as Dolphin on KDE or Thunar on Xfce, or with desktop-agnostic tools like ranger and its descendants. The difference is not feature count; it is governance. nautilus behaviour is settled by the GNOME design team before code is written, which gives the desktop a consistent feel across applications and makes unilateral changes hard. A desktop-agnostic file manager has no such gate, so a feature request can land as a patch, but it also has no desktop integration story to speak of.

A second alternative is to stop modifying the file browser at all and put the functionality somewhere else, for example in a shell script or a separate utility invoked from a launcher. That avoids the extension API entirely and has no ABI exposure, at the cost of not appearing inside the file manager's own menus. Which one is right depends on whether the feature belongs in the file browser or beside it.

Editorial conclusion

Adopt nautilus if you run GNOME and want a file browser whose behaviour you can change through the libnautilus-extension API rather than by patching the binary. Do not adopt it if you need a cross-desktop file manager, a stable extension ABI across releases, or behaviour changes that the GNOME design team has not approved. Before writing an extension, verify that Bubblewrap and LocalSearch are present and working on the machine, because the README lists them as runtime dependencies and search, starred files and batch renaming are tied to LocalSearch. Then check whether the issue you hit reproduces in the Flatpak nightly, since the project only supports the latest upstream version.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository