New in PixInsight 1.8.6: Bundled Projects

Juan Conejero

PixInsight Staff
Staff member
Since version of the PixInsight core application, PixInsight projects can be generated in two flavors: as bundled projects—which is now the default option—, and unbundled projects, or the traditional way.

Bundled projects can change the way you work with projects in PixInsight drastically, hopefully as an important improvement to make your projects more robust and easier to use and maintain. Let's see what bundled projects are and how they are used on different platforms.

Unbundled PixInsight Projects

We'll start with what you already know: unbundled projects consist of an XML project file (.xosm filename suffix) and an associated project data folder (.data suffix), both with the same file name. To work with one of these projects, you just have to concentrate on the XML file: for example, double-click the .xosm file, and the project in question will be opened and loaded in PixInsight, which will detect and manage the associated .data folder automatically and transparently. This works, and all PixInsight users are indeed accustomed to work this way (especially because no other option has been available so far ;) ), but has an important drawback: When you copy or move a project, you should not forget to copy and move both the .xosm file and the .data folder?if you forget one of them, your copied or moved project won't be usable anymore. This can lead to, and actually leads to with relative frequency, important data loses due to simple mistakes.

Bundled PixInsight Projects

A bundled PixInsight project is just a directory (or folder) on which the project's .xosm file and its associated .data directory are stored, along with some additional metadata items. To identify and manage them on all supported platforms, bundled PixInsight projects must carry the .pxiproject filename suffix. The good thing about a bundled project is that it can be handled as a single filesystem item, thus avoiding the possibility to lose one of its components by mistake. For example, to copy a bundled project, you just have to select and drag the bundle as if it were a regular file. Below you can see the icon that identifies PixInsight bundled projects on all platforms.


Now the problem is, given that PixInsight is a multiplatform application, how can we achieve a consistent behavior with respect to bundled projects on Linux/FreeBSD, macOS, and Windows? More specifically, we need to create the illusion that a project's bundle directory is a single .pxiproject file. Well, actually, this is an ideal goal that can only be achieved completely on macOS, but only partially on Linux/FreeBSD and Windows.

So the question is, how are bundled projects seen and managed on each supported platform?


In my opinion, one of the most brilliant characteristics of the macOS operating system (besides the fact that it is UNIX under the hood), is its native implementation of application bundles and document packages. A bundle or package in macOS is just a directory that can be seen and used as a regular file. Applications declare packages as their supported document types, with specific filename suffixes and file icons. This simple filesystem abstraction is one of the facts that makes macOS so easy-to-use and powerful. For example, application bundles have the .app suffix, and Final Cut Pro X libraries are packages with the .fcpbundle suffix. In the same way, bundled PixInsight projects are document packages with the .pxiproject suffix on macOS. Just that simple. So all macOS PixInsight users should be very happy because their projects can now be packages that can be used and managed exactly as regular files, both inside and outside the PixInsight core application.


A bundled PixInsight project selected on Finder (macOS 14.2 Mojave).

X11 Desktops (Linux and FreeBSD) and Windows

Beyond the macOS world a directory is always a directory. That's it. There is no (reasonable, portable) way we can convince a desktop file manager, such as KDE's Dolphin, GNOME's Files, or Windows Explorer, to treat a directory as a single opaque filesystem element, that is, as a regular file.

Outside the PixInsight core application, the status of bundled projects is as follows on Linux and Windows:
  • On desktop file managers, if you press Enter with a .pxiproject directory selected, or double-click it, you'll simply navigate within the directory, but the project won't be opened with PixInsight. You can then double-click the .xosm file to open the bundled project.

  • You can drag a .pxiproject folder directly to PixInsight's workspace to open the bundled project.

  • On Windows, .pxiproject folders will show a custom icon (see above). This is achieved by generating special metadata items automatically (a desktop.ini file, a bundle.ico file, and special system attributes applied to the folder).

  • On the KDE desktop, both 4.x and 5.x versions, all .pxiproject directories will show a custom icon (see above). This is achieved by generating a special .directory file automatically, which KDE detects and interprets transparently. Simple and efficient.


Bundled PixInsight projects shown on KDE's Dolphin file manager (Fedora 29 / KDE Plasma).

  • On other Linux desktops, including GNOME, .pxiproject directories don't have custom icons, unfortunately. Either the required process to assign custom directory icons is too cumbersome and/or platform-dependent, or it simply doesn't exist. I'll try to improve this as possible in future versions.

Inside the PixInsight core application, as you surely have figured out, our goal of having a complete filesystem abstraction for bundled projects has been achieved completely on all supported platforms:
  • On the File Explorer window, you can double-click a .pxiproject folder, or press Enter when it is selected, or drag it to the workspace, to open the bundled project. File Explorer also shows a project thumbnail image and project metadata when you select a .pxiproject package.


Bundled PixInsight projects shown on PixInsight's File Explorer (Fedora 29 / KDE Plasma).

  • When you select the File > Load Project option from the main menu (or press Ctrl+J) on Linux and Windows, a special, non-native file dialog opens where you can open .pxiproject folders as packages, that is, just as regular files (double click, Enter, the Open button, etc). On macOS, native file dialogs support document packages directly.


Bundled PixInsight projects shown on PixInsight's Load PixInsight Project dialog (Fedora 29 / KDE Plasma).

  • On the Save PixInsight Project dialog (File > Save Project, or Shift+Ctrl/Cmd+J), you can choose to save either a bundled or an unbundled project. Again, for bundled projects a special non-native dialog is used to integrate .pxiproject packages with the filesystem on Linux and Windows, while the normal native dialog is used on macOS. The required metadata items will be generated on the bundle directory on all platforms to support all platforms; that is, for example, a .pxiproject package generated on macOS will show its custom icon when copied to Linux/KDE.

  • If you execute the PixInsight core application from a command line, you can specify a .pxiproject package to open it, just as a normal file.

  • The open command can also be used from the Process Console window to open .pxiproject packages.

Bottom Line

The current implementation of bundled projects in PixInsight is only 'perfect' on macOS, since this is the only operating system where the native desktop provides support for the document package abstraction. However, the implementation on X11 (especially on KDE) and Windows desktops is quite satisfactory and fully functional inside the PixInsight core application.

Bundled projects are intended to be a practical, efficient, multiplatform solution to an important problem in PixInsight. There are other possible solutions that I have considered (such as compressed files), but they involve performance penalties and degrade the user's experience on macOS, where packages are the ideal implementation. In addition, the fact that a bundled project is just a directory makes it fully compatible with the unbundled paradigm, that is, you can always open the contained .xosm file on Linux and Windows. I hope you'll find bundled projects to be a useful and robust feature for your next image processing works in PixInsight.