# IPFS Desktop: a Kubo node, a file manager and a menubar menu in one Electron app > IPFS Desktop bundles a full Kubo node with the IPFS Web UI and OS tray shortcuts, so you can add files, pin them and watch peers without opening a terminal. It is a convenience layer, not a headless server, and the README's own troubleshooting list shows where that layer breaks. **ipfs/ipfs-desktop** — An unobtrusive and user-friendly desktop application for IPFS on Windows, Mac and Linux. - Repository: https://github.com/ipfs/ipfs-desktop - Website: https://docs.ipfs.tech/install/ipfs-desktop/ - Stars: 6,589 · Forks: 906 - Language: JavaScript - License: MIT - Published: 2026-09-22 · Updated: 2026-09-22 · Language: en - Canonical page: https://hysenlabs.com/projects/ipfs-ipfs-desktop ## What IPFS Desktop actually solves for a first-time node operator Running Kubo from a shell asks you to learn a daemon, a repository layout, a gateway port and a set of subcommands before you can add a single file. IPFS Desktop removes that first step. The README describes it as "a complete IPFS node, plus handy OS menubar/taskbar shortcuts and an all-in-one file manager, peer map, and content explorer." The node is Kubo, the interface is the IPFS Web UI, and the app wraps both in Electron. The audience is split in two. The first group has never touched IPFS and wants to add a folder, get a CID and share a link. The second group already runs a node and wants tray controls, drag-and-drop imports and screenshot capture without leaving the desktop. The README states this directly: use it "to get acquainted with IPFS without needing to touch the terminal", or, if you are experienced, use the shortcuts "alongside the command line". What it is not is a server product. There is no mention of a headless mode, a systemd unit or a container image in the README. The distribution formats are a Windows installer, a macOS disk image and a Linux AppImage, all of which assume a logged-in desktop session. ## How the Electron shell, Kubo and the Web UI fit together The repository layout makes the architecture reasonably clear. package.json sets `"main": "src/index.js"` and names the product `IPFS Desktop`, so the Electron main process is the entry point. The build script is a chain: `clean`, then `build:webui`, which copies a local Web UI build or downloads one, then strips source maps. The downloaded asset is fetched by CID through `ipfs-or-gateway`, with a `trustless-gateway.link` fallback. In other words, the interface you see is a prebuilt IPFS Web UI shipped inside the app, not something generated at runtime. The node side is a dependency rather than a rewrite. The `clean` script removes `node_modules/kubo/bin`, and `postinstall` runs `install-app-deps`, `patch-deps` and `macos-universal-kubo`. On macOS there is a dedicated script that builds a universal Kubo binary. So the app ships a Kubo binary and starts it as a child process. That design explains the behaviour the README describes in the features section: if a node already exists, IPFS Desktop "will act as a control panel and file browser for that node"; if not, "it'll install one for you". The app is a supervisor and a view over a daemon that could equally be started by hand. The FAQ entry on repo location exists precisely because this dual role creates ambiguity about which repository is in use. The tray menu is the third piece. It exposes stop and restart, and on Mac and Windows the app can be set to launch at system startup so the node is running whenever the machine is on. Linux users get a reduced experience, which the README acknowledges in its own troubleshooting entry about the missing system tray menu. ## Installing IPFS Desktop on Windows, Mac and Linux The README's quick-install section points at release assets for the current version, 0.50.1, and recommends these over other package formats because they include an automatic update mechanism. The three links are a Windows x64 installer, a macOS disk image and a Linux x86_64 AppImage. If you prefer to manage updates yourself, the README directs you to the other package formats under its install section rather than listing them in the quick-install block. On Linux, the AppImage needs FUSE; the README has a dedicated FAQ entry for the FUSE error, so treat that as a known first hurdle rather than a surprise. Building from source is a supported path. The repository has a `start` script that runs Electron in development mode: ```bash npm install npm start ``` The `start` script is defined as `cross-env NODE_ENV=development electron .`, so `npm start` launches the app against your working tree. `postinstall` handles the native dependency rebuild, the patch step and, on macOS, the universal Kubo binary. For a first real use, the Files screen is the entry point. The README lists four ways to add content: drag and drop onto the Files screen, the Import button (which accepts either local items or a CID), a Windows right-click menu entry, and dragging onto the IPFS logo in the macOS menubar. After an import you should see the item listed with its CID, and it can be pinned from there. The Explore screen is where you inspect the Merkle forest of a given CID, and the Peers screen shows the peer map. ## Where IPFS Desktop is the wrong tool The most obvious mismatch is headless deployment. Nothing in the README describes running IPFS Desktop on a server, and the AppImage and installer formats assume a graphical session. If you want a node on a VPS, Kubo on its own is the smaller and more controllable option. The second mismatch is scripting. The app is a GUI over a daemon; the README's own framing puts the command line alongside the app rather than inside it. If your workflow is CI jobs, cron pinning or shell pipelines, the tray menu adds nothing. There is also a class of failure the README documents at length, and it is worth reading before you file a bug. A `repo.lock` error means another process already holds the repository, which happens when a second node, or a second copy of the app, is pointed at the same repo. Network errors such as `Error fetching` are listed as their own entry. There are entries for daemon initialization failures, for a program version lower than the repository version, and for outdated `fs-repo` migrations that fail with a context deadline exceeded. One entry is titled, plainly, "The daemon failed to start and produced no output." That list is a fair picture of the surface area: the app is a supervisor, and supervisors inherit every failure mode of the process they supervise. Platform support is uneven. The README's own FAQ asks why the system tray menu is missing on Linux, and there are separate notes for Debian 10 and Debian 11, plus a GTK 2/3 versus GTK 4 symbol conflict. Linux is supported, but it is the platform with the most caveats. ## IPFS Desktop versus Kubo, IPFS Companion and a gateway The nearest alternative is Kubo itself, the daemon IPFS Desktop embeds. The difference is who owns the node. With Kubo you install the binary, run `ipfs init`, start the daemon and drive everything through subcommands; you decide the repo path, the ports and the startup behaviour. With IPFS Desktop, the app decides when the daemon starts, offers stop and restart from the tray, and can launch at login. The trade is control for convenience, and the README's FAQ entries about repo location and boot flags exist because that control has moved. IPFS Companion is a different thing entirely. It is a browser extension, and the RELATED searches show people conflate the two. Companion does not run a node on your machine in the way the README describes for Desktop; it redirects requests and talks to a node. If your problem is "links in my browser do not resolve", Companion is the smaller intervention. If your problem is "I want to add and pin files locally", Desktop is the one with the Files screen. A public gateway is the third option and the least committed. It requires no install and no disk, but it also means you are not hosting anything, and the README's framing of Desktop as giving you "all the power of IPFS" locally does not apply. The release notes and README do not compare the app to gateways, so treat this as a category distinction rather than a documented claim. ## Maintenance, release cadence and what the MIT licence covers The repository is not archived and the last push was on 2026-09-17. Recent releases are v0.50.1 on 2026-09-15, v0.50.0 on 2026-08-03 and v0.49.1 on 2026-06-09. That is roughly a release every six to eight weeks across the visible window, with a patch following the minor release by about two weeks. The upgrade story depends on which format you choose, and the README is explicit about the split. The Windows installer, macOS disk image and Linux AppImage are described as having a built-in automatic update mechanism, and the README recommends them "when in doubt". If you take a different package format, the README says you manage updates yourself. That is a real operational difference, not a cosmetic one: the auto-updating formats keep the bundled Kubo current, while a manually managed install can drift behind the repository version and hit the migration errors the FAQ describes. On licensing, the repository ships an MIT `LICENSE` file and package.json marks the package `"private": true`, which means it is not published to npm as a consumable library. MIT is permissive and permits reuse and redistribution with the licence and copyright notice retained, but this article is not legal advice. One practical point the README makes: because the app bundles a Kubo binary and a downloaded Web UI asset, the distributed artifact contains more than the JavaScript in this repository, so anyone redistributing a build should look at what else is inside it. ## Conclusion Adopt IPFS Desktop if you want a Kubo node running on a laptop with drag-and-drop adding, pinning and a peer map, and you accept that the app manages the node rather than replacing it. Skip it if you need a headless daemon on a server, a browser extension for gateway redirection, or a CLI you script against; Kubo alone covers those. Before installing, check that the package format matches your distro (the README lists separate notes for Debian 10 and 11 and a FUSE error for the AppImage), and confirm where the app will put the repo, because the README says it reuses an existing node's repository when one is found. ## FAQ ### What is IPFS Desktop? It is a desktop application that combines a complete IPFS node running Kubo with the IPFS Web UI, plus menubar or system tray shortcuts and a file manager, peer map and content explorer. The README describes it as a way to get acquainted with IPFS without touching the terminal, or to complement the command line if you already use it. ### How do I use IPFS Desktop to add a file? Open the Files screen and either drag and drop items onto it, or click the Import button to add items from your computer or from a CID. Windows users can also right-click a file or folder and add it from the pop-up menu, and Mac users can drag a file onto the IPFS logo in the menubar. ### Is IPFS Desktop free? The repository is licensed under MIT, and the README points to release downloads for Windows, Mac and Linux without any pricing step. The licence permits reuse and redistribution provided the notice is retained. ### Which operating systems does IPFS Desktop support? The README gives install paths for Windows, Mac and Linux/FreeBSD, and the quick-install links cover a Windows x64 installer, a macOS disk image and a Linux x86_64 AppImage. Linux carries the most caveats, including a missing system tray menu and separate notes for Debian 10 and 11. ### Why does IPFS Desktop fail to start with a repo.lock error? The README has a dedicated entry for this error, which indicates the repository is already held by another process. The FAQ also covers related startup failures such as the daemon producing no output, a program version lower than the repository version, and outdated fs-repo migrations. ## Sources - [ipfs/ipfs-desktop on GitHub](https://github.com/ipfs/ipfs-desktop) - [License: MIT](https://github.com/ipfs/ipfs-desktop/blob/main/LICENSE) - [Project website](https://docs.ipfs.tech/install/ipfs-desktop/) - [README](https://github.com/ipfs/ipfs-desktop/blob/main/README.md) - [Releases](https://github.com/ipfs/ipfs-desktop/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ipfs-ipfs-desktop