fix: fetch binary on demand from github releases#83
Merged
Conversation
npm v12 makes dependency install scripts opt-in, so the postinstall
step that downloads the kubo binary stops running in many setups
(npm install --ignore-scripts, pnpm, hardened CI), and path() then
throws "kubo binary not found".
The binary now downloads on first use when missing, reusing the same
caching, checksum and symlink logic as the postinstall path:
- path() fetches the binary when absent; KUBO_BINARY and a new
{ autoDownload: false } opt-out still short-circuit it
- bin/ipfs is a shim that resolves the binary and runs it, so the CLI
works without the postinstall symlink
- installer output goes to stderr and a failed download throws the
clean "kubo binary not found" error, so path() keeps a quiet stdout
- README documents on-demand install and cross-project/CI caching
Fetch release assets from GitHub instead of dist.ipfs.tech. Asset URLs are built from the version, OS and arch, so no version index or dist.json manifest is fetched. - default source is https://github.com/ipfs/kubo/releases; override with KUBO_RELEASES_URL or kubo.releasesUrl, which also work for HTTP mirrors - KUBO_DIST_URL / GO_IPFS_DIST_URL / kubo.distUrl still work via the old layout but print a deprecation warning - a 404 tells a missing release apart from a missing platform asset, and suggests retrying later if the release is still publishing - the cache writes the archive only after both files are fetched, so a failed checksum download no longer poisons it
Read the pinned version from package-lock.json so the GitHub Actions cache key tracks kubo upgrades without a manual bump.
1 task
On a git install npm runs postinstall before node_modules/kubo/bin exists, so link() failed with ENOENT when symlinking the binary into it. Create the directory first. Registry installs already had it, so this only affects installs from a git url.
This was referenced Jun 28, 2026
achingbrain
approved these changes
Jul 3, 2026
lidel
added a commit
to ipfs/ipfs-desktop
that referenced
this pull request
Jul 3, 2026
ipfs/npm-kubo#83 (on-demand binary fetch from github releases) landed on master. Pin the kubo dependency to that merge commit and drop the macos build TODO that was gating the switch.
lidel
added a commit
to ipfs/ipfs-desktop
that referenced
this pull request
Jul 3, 2026
ipfs/npm-kubo#83 (on-demand binary fetch from github releases) landed on master. Pin the kubo dependency to the latest npm-kubo master commit and drop the macos build TODO that was gating the switch.
1 task
This was referenced Jul 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
People hit "kubo binary not found", and the ipfs-desktop daemon won't start (ipfs/ipfs-desktop#3031).
This package downloads the kubo binary in a
postinstallscript, so the binary goes missing whenever npm skips that script. npm v12 makes install scripts opt-in by default, and--ignore-scripts, pnpm, and hardened CI already skip them today. Every download also went through dist.ipfs.tech which is extra infrastructure that someone needs to run.Fix
path()or theipfsshim) whenpostinstalldid not run, so it works with or without scripts.KUBO_DIST_URLstill works with a deprecation warning; the newKUBO_RELEASES_URLpoints at GitHub or any mirror.Installs are now reliable under npm v12, with GitHub as the CDN. The kubo version a project gets is unchanged, and dist.ipfs.tech still works for anyone who sets
KUBO_DIST_URL.Tested in:
seems to work fine