ipfs 0.39.0 #256166
Merged
ipfs 0.39.0 #256166
Conversation
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
github-actions
bot
added
go
stefanb
approved these changes
Nov 27, 2025
Contributor
|
🤖 An automated task has requested bottles to be published to this PR. Caution Please do not push to this PR branch before the bottle commits have been pushed, as this results in a state that is difficult to recover from. If you need to resolve a merge conflict, please use a merge commit. Do not force-push to this PR branch. |
github-actions
bot
added
the
CI-published-bottle-commits
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Created by
brew bumpCreated with
brew bump-formula-pr.Details
release notes
ipfs provide statprovider_provides_totalgo-ipfsname no longer publishedOverview
This release is an important step toward solving the DHT bottleneck for self-hosting IPFS on consumer hardware and home networks. The DHT sweep provider (now default) announces your content to the network without traffic spikes that overwhelm residential connections. Automatic UPnP recovery means your node stays reachable after router restarts without manual intervention.
New content becomes findable immediately after
ipfs add. The provider system persists state across restarts, alerts you when falling behind, and exposes detailed stats for monitoring. This release also finalizes the deprecation of the legacygo-ipfsname.🔦 Highlights
🎯 DHT Sweep provider is now the default
The Amino DHT Sweep provider system, introduced as experimental in v0.38, is now enabled by default (
Provide.DHT.SweepEnabled=true).What this means: All nodes now benefit from efficient keyspace-sweeping content announcements that reduce memory overhead and create predictable network patterns, especially for nodes providing large content collections.
Migration: The transition is automatic on upgrade. Your existing configuration is preserved:
Provide.DHT.SweepEnabled=falsein v0.38, you'll continue using the legacy provideripfs config --json Provide.DHT.SweepEnabled falseNew features available with sweep mode:
ipfs provide stat(see below)provider_provides_total) (see below)For background on the sweep provider design and motivations, see
Provide.DHT.SweepEnabledand Shipyard's blogpost Provide Sweep: Solving the DHT Provide Bottleneck.⚡ Fast root CID providing for immediate content discovery
When you add content to IPFS, the sweep provider queues it for efficient DHT provides over time. While this is resource-efficient, other peers won't find your content immediately after
ipfs addoripfs dag importcompletes.To make sharing faster,
ipfs addandipfs dag importnow do an immediate provide of root CIDs to the DHT in addition to the regular queue (controlled by the new--fast-provide-rootflag, enabled by default). This complements the sweep provider system: fast-provide handles the urgent case (root CIDs that users share and reference), while the sweep provider efficiently provides all blocks according toProvide.Strategyover time.This closes the gap between command completion and content shareability: root CIDs typically become discoverable on the network in under a second (compared to 30+ seconds previously). The feature uses optimistic DHT operations, which are significantly faster with the sweep provider (now enabled by default).
By default, this immediate provide runs in the background without blocking the command. For use cases requiring guaranteed discoverability before the command returns (e.g., sharing a link immediately), use
--fast-provide-waitto block until the provide completes.Simple examples:
Configuration: Set defaults via
Import.FastProvideRoot(default:true) andImport.FastProvideWait(default:false). Seeipfs add --helpandipfs dag import --helpfor more details and examples.This optimization works best with the sweep provider and accelerated DHT client, where provide operations are significantly faster. Automatically skipped when DHT is unavailable (e.g.,
Routing.Type=noneor delegated-only configurations).⏯️ Provider state persists across restarts
The Sweep provider now persists the reprovide cycle state and automatically resumes where it left off after a restart. This brings several improvements:
Provide.DHT.ResumeEnabled(default:true). Set tofalseif you don't want to keep the persisted provider state from a previous run.This feature improves reliability for nodes that experience intermittent connectivity or restarts.
📊 Detailed statistics with
ipfs provide statThe Sweep provider system now exposes detailed statistics through
ipfs provide stat, helping you monitor provider health and troubleshoot issues.Run
ipfs provide statfor a quick summary, or use--allto see complete metrics including connectivity status, queue sizes, reprovide schedules, network statistics, operation rates, and worker utilization. For real-time monitoring, usewatch ipfs provide stat --all --compactto observe changes in a 2-column layout. Individual sections can be displayed with flags like--network,--operations, or--workers.For Dual DHT configurations, use
--lanto view LAN DHT statistics instead of the default WAN DHT stats.For more information, run
ipfs provide stat --helpor see the Provide Stats documentation, including Capacity Planning.🔔 Slow reprovide warnings
Kubo now monitors DHT reprovide operations when
Provide.DHT.SweepEnabled=trueand alerts you if your node is falling behind on reprovides.
When the reprovide queue consistently grows and all periodic workers are busy,
a warning displays with:
Provide.DHT.MaxWorkersorProvide.DHT.DedicatedPeriodicWorkerswatch ipfs provide stat --all --compactThe alert polls every 15 minutes (to avoid alert fatigue while catching
persistent issues) and only triggers after sustained growth across multiple
intervals. The legacy provider is unaffected by this change.
📊 Metric rename:
provider_provides_totalThe Amino DHT Sweep provider metric has been renamed from
total_provide_count_totaltoprovider_provides_totalto follow OpenTelemetry naming conventions and maintain consistency with other kad-dht metrics (which use dot notation likerpc.inbound.messages,rpc.outbound.requests, etc.).Migration: If you have Prometheus queries, dashboards, or alerts monitoring the old
total_provide_count_totalmetric, update them to useprovider_provides_totalinstead. This affects all nodes using sweep mode, which is now the default in v0.39 (previously opt-in experimental in v0.38).🔧 Automatic UPnP recovery after router restarts
Kubo now automatically recovers UPnP port mappings when routers restart or
become temporarily unavailable, fixing a critical connectivity issue that
affected self-hosted nodes behind NAT.
Previous behavior: When a UPnP-enabled router restarted, Kubo would lose
its port mapping and fail to re-establish it automatically. Nodes would become
unreachable to the network until the daemon was manually restarted, forcing
reliance on relay connections which degraded performance.
New behavior: The upgraded go-libp2p (v0.44.0) includes Shipyard's fix
for self-healing NAT mappings that automatically rediscover and re-establish
port forwarding after router events. Nodes now maintain public connectivity
without manual intervention.
This significantly improves reliability for desktop and self-hosted IPFS nodes
using UPnP for NAT traversal.
🪦 Deprecated
go-ipfsname no longer publishedThe
go-ipfsname was deprecated in 2022 and renamed tokubo. Starting with this release, the legacy Docker image name has been replaced with a stub that displays an error message directing users to switch toipfs/kubo.Docker images: The
ipfs/go-ipfsimage tags now contain only a stub script that exits with an error, instructing users to update their Docker configurations to useipfs/kuboinstead. This ensures users are aware of the deprecation while allowing existing automation to fail explicitly rather than silently using outdated images.Distribution binaries: Download Kubo from https://dist.ipfs.tech/kubo/ or https://github.com/ipfs/kubo/releases. The legacy
go-ipfsdistribution path should no longer be used.All users should migrate to the
kuboname in their scripts and configurations.🚦 Gateway range request limits for CDN compatibility
The new
Gateway.MaxRangeRequestFileSizeconfiguration protects against CDN range request limitations that cause bandwidth overcharges on deserialized responses. Some CDNs convert range requests over large files into full file downloads, causing clients requesting small byte ranges to unknowingly download entire multi-gigabyte files.This only impacts deserialized responses. Clients using verifiable block requests (
application/vnd.ipld.raw) are not affected. See the configuration documentation for details.🖥️ RISC-V support with prebuilt binaries
Kubo provides official
linux-riscv64prebuilt binaries, bringing IPFS to RISC-V open hardware.As RISC-V single-board computers and embedded systems become more accessible, the distributed web is now supported on open hardware architectures - a natural pairing of open technologies.
Download from https://dist.ipfs.tech/kubo/ or https://github.com/ipfs/kubo/releases and look for the
linux-riscv64archive.📦️ Important dependency updates
go-libp2pto v0.45.0 (incl. v0.44.0) with self-healing UPnP port mappings and go-log/slog interop fixesquic-goto v0.55.0go-logto v2.9.0 with slog integration for go-libp2pgo-ds-pebbleto v0.5.7 (includes pebble v2.1.2)boxoto v0.35.2 (includes boxo v0.35.1)ipfs-webuito v4.10.0go-libp2p-kad-dhtto v0.36.0📝 Changelog
Full Changelog
dag import(#11058) (ipfs/kubo#11058)ipfs provide stat(#11019) (ipfs/kubo#11019)--flush=false(#10985) (ipfs/kubo#10985)SweepingProvider.wg(#1200) (libp2p/go-libp2p-kad-dht#1200)RegionsFromPeersmay return multiple regions (#1185) (libp2p/go-libp2p-kad-dht#1185)👨👩👧👦 Contributors
View the full release notes at https://github.com/ipfs/kubo/releases/tag/v0.39.0.