github ipfs/kubo v0.40.0
on GitHub

4 hours ago

Note

This release was brought to you by the Shipyard team.

  • 🔦 Highlights
    • 🔢 IPIP-499: UnixFS CID Profiles
    • 🧹 Automatic cleanup of interrupted imports
    • 🌍 Light clients can now use your node for delegated routing
    • 📊 See total size when pinning
    • 🔀 IPIP-523: ?format= takes precedence over Accept header
    • 🚫 IPIP-524: Gateway codec conversion disabled by default
    • ✅ More reliable IPNS over PubSub
    • 🗄️ New ipfs diag datastore commands
    • 🔍 New ipfs swarm addrs autonat command
    • 🚇 Improved ipfs p2p tunnels with foreground mode
    • 📊 Friendlier ipfs dag stat output
    • 🔑 ipfs key improvements
    • 🤝 More reliable content providing after startup
    • 🌐 No unnecessary DNS lookups for AutoTLS addresses
    • ⏱️ Configurable gateway request duration limit
    • 🔧 Recovery from corrupted MFS root
    • 📡 RPC Content-Type headers for binary responses
    • 🔖 New ipfs name get|put commands
    • 📋 Long listing format for ipfs ls
    • 🖥️ WebUI Improvements
    • 📉 Fixed Prometheus metrics bloat on popular subdomain gateways
    • 📢 libp2p announces all interface addresses
    • 🗑️ Badger v1 datastore slated for removal this year
    • 🐹 Go 1.26
    • 📦️ Dependency updates
  • 📝 Changelog
  • 👨‍👩‍👧‍👦 Contributors

🔦 Highlights

This release brings reproducible file imports (CID Profiles), cleanup of interrupted flatfs operations, better connectivity diagnostics, and improved gateway behavior. It also ships with Go 1.26, lowering memory usage and GC overhead across the board.

🔢 IPIP-499: UnixFS CID Profiles

CID Profiles are presets that pin down how files get split into blocks and organized into directories, so you get the same CID for the same data across different software or versions. Defined in IPIP-499.

New configuration profiles

  • unixfs-v1-2025: modern CIDv1 profile with improved defaults
  • unixfs-v0-2015 (alias legacy-cid-v0): best-effort legacy CIDv0 behavior

Apply with: ipfs config profile apply unixfs-v1-2025

The test-cid-v1 and test-cid-v1-wide profiles have been removed. Use unixfs-v1-2025 or manually set specific Import.* settings instead.

New Import.* options

  • Import.UnixFSHAMTDirectorySizeEstimation: estimation mode (links, block, or disabled)
  • Import.UnixFSDAGLayout: DAG layout (balanced or trickle)

New ipfs add CLI flags

  • --dereference-symlinks resolves all symlinks to their target content, replacing the deprecated --dereference-args which only resolved CLI argument symlinks
  • --empty-dirs / -E controls inclusion of empty directories (default: true)
  • --hidden / -H includes hidden files (default: false)
  • --trickle implicit default can be adjusted via Import.UnixFSDAGLayout

ipfs files write fix for CIDv1 directories

When writing to MFS directories that use CIDv1 (via --cid-version=1 or ipfs files chcid), single-block files now produce raw block CIDs (like bafkrei...), matching the behavior of ipfs add --raw-leaves. Previously, MFS would wrap single-block files in dag-pb even when raw leaves were enabled. CIDv0 directories continue to use dag-pb.

Block size limit raised to 2MiB

ipfs block put, ipfs dag put, and ipfs dag import now accept blocks up to 2MiB without --allow-big-block, matching the bitswap spec. The previous 1MiB limit was too restrictive and broke ipfs dag import of 1MiB-chunked non-raw-leaf data (protobuf wrapping pushes blocks slightly over 1MiB). The max --chunker value for ipfs add is 2MiB - 256 bytes to leave room for protobuf framing. IPIP-499 profiles use lower chunk sizes (256KiB and 1MiB) and are not affected.

HAMT Threshold Fix

HAMT directory sharding threshold changed from >= to > to match the Go docs and JS implementation (ipfs/boxo@6707376). A directory exactly at 256 KiB now stays as a basic directory instead of converting to HAMT. This is a theoretical breaking change, but unlikely to impact real-world users as it requires a directory to be exactly at the threshold boundary. If you depend on the old behavior, adjust Import.UnixFSHAMTShardingSize to be 1 byte lower.

🧹 Automatic cleanup of interrupted imports

If you cancel ipfs add or ipfs dag import mid-operation, Kubo now automatically cleans up incomplete data on the next daemon start. Previously, interrupted imports would leave orphan blocks in your repository that were difficult to identify and remove without pins and running explicit garbage collection.

Batch operations also use less memory now. Block data is written to disk immediately rather than held in RAM until the batch commits.

Under the hood, the block storage layer (flatfs) was rewritten to use atomic batch operations via a temporary staging directory. See go-ds-flatfs#142 for details.

🌍 Light clients can now use your node for delegated routing

The Routing V1 HTTP API is now exposed by default at http://127.0.0.1:8080/routing/v1. This allows light clients in browsers to use Kubo Gateway as a delegated routing backend instead of running a full DHT client. Support for IPIP-476: Delegated Routing DHT Closest Peers API is included. Can be disabled via Gateway.ExposeRoutingAPI.

📊 See total size when pinning

ipfs pin add --progress now shows the total size of the pinned DAG as it fetches blocks.

Example output: 

Fetched/Processed 336 nodes (83 MB)

🔀 IPIP-523: ?format= takes precedence over Accept header

The ?format= URL query parameter now always wins over the Accept header (IPIP-523), giving you deterministic HTTP caching and protecting against CDN cache-key collisions. Browsers can also use ?format= reliably even when they send Accept headers with specific content types.

The only breaking change is for edge cases where a client sends both a specific Accept header and a different ?format= value for an explicitly supported format (tar, raw, car, dag-json, dag-cbor, etc.). Previously Accept would win. Now ?format= always wins.

🚫 IPIP-524: Gateway codec conversion disabled by default

Gateways no longer convert between codecs by default (IPIP-524). This removes gateways from a gatekeeping role: clients can adopt new codecs immediately without waiting for gateway operator updates. Requests for a format that differs from the block's codec now return 406 Not Acceptable.

Migration: Clients should fetch raw blocks (?format=raw or Accept: application/vnd.ipld.raw)
and convert client-side using libraries like @helia/verified-fetch.

Set Gateway.AllowCodecConversion
to true to restore previous behavior.

✅ More reliable IPNS over PubSub

IPNS over PubSub implementation in Kubo is now more reliable. Duplicate messages are rejected even in large networks where messages may cycle back after the in-memory cache expires.

Kubo now persists the maximum seen sequence number per peer to the datastore (go-libp2p-pubsub#BasicSeqnoValidator), providing stronger duplicate detection that survives node restarts. This addresses message flooding issues reported in #9665.

IPNS over PubSub is opt-in via Ipns.UsePubsub. Kubo's pubsub is optimized for IPNS use case. For custom pubsub applications requiring different validation logic, use go-libp2p-pubsub directly in a dedicated binary.

🗄️ New ipfs diag datastore commands

New experimental commands for low-level datastore inspection:

  • ipfs diag datastore get <key> - Read raw value at a datastore key (use --hex for hex dump)
  • ipfs diag datastore count <prefix> - Count entries matching a datastore prefix

The daemon must not be running when using these commands. Run ipfs diag datastore --help for usage examples.

🔍 New ipfs swarm addrs autonat command

The new ipfs swarm addrs autonat command shows the network reachability status of your node's addresses as verified by AutoNAT V2. AutoNAT V2 leverages other nodes in the IPFS network to test your node's external public reachability, providing a self-service way to debug connectivity.

Public reachability is important for:

  • Direct data fetching: Other nodes can fetch data directly from your node without NAT hole punching.
  • Browser access: Web browsers can connect to your node directly for content retrieval.
  • DHT participation: Your node can act as a DHT server, helping to maintain the distributed hash table and making content routing more robust.

The command displays:

  • Overall reachability status (public, private, or unknown)
  • Per-address reachability showing which specific addresses are reachable, unreachable, or unknown

Example output: 

AutoNAT V2 Status:
  Reachability: public

Per-Address Reachability:
  Reachable:
    /ip4/203.0.113.42/tcp/4001
    /ip4/203.0.113.42/udp/4001/quic-v1
  Unreachable:
    /ip6/2001:db8::1/tcp/4001
  Unknown:
    /ip4/203.0.113.42/udp/4001/webrtc-direct

This helps diagnose connectivity issues and understand if your node is publicly reachable. See the AutoNAT V2 spec for more details.

🚇 Improved ipfs p2p tunnels with foreground mode

P2P tunnels can now run like SSH port forwarding: start a tunnel, use it, and it cleans up automatically when you're done.

The new --foreground (-f) flag for ipfs p2p listen and ipfs p2p forward keeps the command running until interrupted. When you Ctrl+C, send SIGTERM, or stop the service, the tunnel is removed automatically: 

$ ipfs p2p listen /x/ssh /ip4/127.0.0.1/tcp/22 --foreground
Listening on /x/ssh, forwarding to /ip4/127.0.0.1/tcp/22, waiting for interrupt...
^C
Received interrupt, removing listener for /x/ssh

Without --foreground, commands return immediately and tunnels persist until explicitly closed (existing behavior).

See docs/p2p-tunnels.md for usage examples.

📊 Friendlier ipfs dag stat output

The ipfs dag stat command has been improved for better terminal UX:

  • Progress output now uses a single line with carriage return, avoiding terminal flooding
  • Progress is auto-detected: shown only in interactive terminals by default
  • Human-readable sizes are now displayed alongside raw byte counts

Example progress (interactive terminal): 

Fetched/Processed 84 blocks, 2097152 bytes (2.1 MB)

Example summary output: 

Summary
Total Size: 2097152 (2.1 MB)
Unique Blocks: 42
Shared Size: 1048576 (1.0 MB)
Ratio: 1.500000

Use --progress=true to force progress even when piped, or --progress=false to disable it.

🔑 ipfs key improvements

ipfs key ls is now the canonical command for listing keys, matching ipfs pin ls and ipfs files ls. The old ipfs key list still works but is deprecated.

Listing also became more resilient: bad keys are now skipped with an error log instead of failing the entire operation.

🤝 More reliable content providing after startup

Previously, provide operations could start before the Accelerated DHT Client discovered enough peers, causing sweep mode to lose its efficiency benefits. Now, providing waits for the initial network crawl (about 10 minutes). Your content will be properly distributed across DHT regions after initial DHT map is created. Check ipfs provide stat to see when providing begins.

🌐 No unnecessary DNS lookups for AutoTLS addresses

Kubo no longer makes DNS queries for AutoTLS addresses like 1-2-3-4.peerid.libp2p.direct. Since the IP is encoded in the hostname (1-2-3-4 means 1.2.3.4), Kubo extracts it locally. This reduces load on the public good DNS servers at libp2p.direct run by Shipyard, reserving them for web browsers which lack direct DNS access and must rely on the browser's resolver.

To disable, set AutoTLS.SkipDNSLookup to false.

⏱️ Configurable gateway request duration limit

Gateway.MaxRequestDuration sets an absolute deadline for gateway requests. Unlike RetrievalTimeout (which resets on each data write and catches stalled transfers), this is a hard limit on the total time a request can take.

The default 1 hour limit (previously hardcoded) can now be adjusted to fit your deployment needs. This is a fallback that prevents requests from hanging indefinitely when subsystem timeouts are misconfigured or fail to trigger. Returns 504 Gateway Timeout when exceeded.

🔧 Recovery from corrupted MFS root

If your daemon fails to start because the MFS root is not a directory (due to misconfiguration, operational error, or disk corruption), you can now recover without deleting and recreating your repository in a new IPFS_PATH.

The new ipfs files chroot command lets you reset the MFS (Mutable File System) root or restore it to a known valid CID: 

# Reset MFS to an empty directory
$ ipfs files chroot --confirm

# Or restore from a previously saved directory CID
$ ipfs files chroot --confirm QmYourBackupCID

See ipfs files chroot --help for details.

📡 RPC Content-Type headers for binary responses

HTTP RPC endpoints that return binary data now set appropriate Content-Type headers, making it easier to integrate with HTTP clients and tooling that rely on MIME types. On CLI these commands behave the same as before, but over HTTP RPC you now get proper headers:

Endpoint Content-Type
/api/v0/get application/x-tar or application/gzip
/api/v0/dag/export application/vnd.ipld.car
/api/v0/block/get application/vnd.ipld.raw
/api/v0/name/get application/vnd.ipfs.ipns-record
/api/v0/diag/profile application/zip

🔖 New ipfs name get|put commands

You can now backup, restore, and share IPNS records without needing the private key. 

$ ipfs name get /ipns/k51... > record.bin
$ ipfs name get /ipns/k51... | ipfs name inspect
$ ipfs name put k51... record.bin

These are low-level tools primarily for debugging and testing IPNS.

The put command validates records by default. Use --force to skip validation and test how routing systems handle malformed or outdated records. Note that --force only bypasses this command's checks; the routing system may still reject invalid records.

📋 Long listing format for ipfs ls

The ipfs ls command now supports --long (-l) flag for displaying Unix-style file permissions and modification times. This works with files added using --preserve-mode and --preserve-mtime. See ipfs ls --help for format details and examples.

🖥️ WebUI Improvements

IPFS Web UI has been updated to v4.11.0.

Search and filter files

You can now search and filter files directly in the Files screen. Type a name, CID, or file extension and the list narrows down in real time. Works in both list and grid view.

Search and filter files

DHT Provide diagnostic screen

New screen under Diagnostics that shows the health of DHT Provide operations. You can see reprovide cycle progress, worker utilization, queue status, and network throughput at a glance, without having to use the ipfs provide stat CLI.

DHT Provide diagnostic screen

Better path handling in Files

The Inspect button now resolves /ipfs/ and /ipns/ paths to their final CID before opening the IPLD Explorer. The Explore form also accepts ipfs:// and ipns:// protocol URLs. Previously, these would show a blank screen or an infinite spinner. Path resolution errors now also show better error pages:

Better path handling in Files

📉 Fixed Prometheus metrics bloat on popular subdomain gateways

Most Kubo users are unaffected by this change. It matters if you run Kubo as a public subdomain gateway (with Gateway.PublicGateways and UseSubdomains: true), where the otelhttp instrumentation was including the raw Host header as the server_address metric label. Every unique hostname (e.g., each CID.ipfs.dweb.link) created a separate time series, resulting in millions of metric lines, multi-gigabyte /debug/metrics/prometheus responses, and Prometheus scrape timeouts.

What changed:

  • http_server_* metrics replace the unbounded server_address label with a new server_domain label that groups requests by gateway domain:
    • Gateway: matched Gateway.PublicGateways suffix (e.g., dweb.link, ipfs.io), or localhost, loopback, other
    • RPC API: api / Libp2p Gateway: libp2p
  • Prometheus exemplars are disabled to prevent log noise from long subdomain hostnames. Tracing spans are unaffected.

If you use Rainbow for your public gateway (recommended), this issue never applied to you -- Rainbow uses its own low-cardinality HTTP metrics.

📢 libp2p announces all interface addresses

go-libp2p v0.47.0 includes a rewritten routing library (go-netroute) that fixes interop with VPN and WireGuard/Tailscale setups. A side effect: when listening on 0.0.0.0, libp2p now returns addresses from all network interfaces instead of just the primary one (go-libp2p#3460).

This means easier connectivity and less manual configuration for most desktop, VPN, and self-hosted users. However, if you don't run with the server profile and have an empty Addresses.NoAnnounce, your node may now announce internal addresses (e.g. Docker bridge 172.17.0.0/16 or Tailscale 100.64.0.0/10) to the DHT. In the default setup, AutoNAT will probe and mark unreachable ones as offline and they won't be listed, but you can also filter them out explicitly.

To check what your node announces and filter out unwanted ranges: 

$ ipfs swarm addrs local
$ ipfs config --json Addresses.NoAnnounce '["/ip4/172.17.0.0/ipcidr/16"]'

The server profile already filters common private ranges via Addresses.NoAnnounce.

🗑️ Badger v1 datastore slated for removal this year

The badgerds datastore (based on badger 1.x) is slated for removal. Badger v1 has not been maintained by its upstream maintainers for years and has known bugs including startup timeouts, shutdown hangs, and file descriptor exhaustion. Starting with this release, every daemon start with a badger-based repository prints a loud deprecation error on stderr.

See the badgerds profile documentation for migration guidance, and #11186 for background.

🐹 Go 1.26

This release is built with Go 1.26.

You should see lower memory usage and reduced GC pauses thanks to the new Green Tea garbage collector (10-40% less GC overhead). Reading block data and API responses is faster due to io.ReadAll improvements (~2x faster, ~50% less memory). On 64-bit platforms, heap base address randomization adds a layer of security hardening.

📦️ Dependency updates

📝 Changelog

Full Changelog

👨‍👩‍👧‍👦 Contributors

Contributor Commits Lines ± Files Changed
@lidel 62 +18446/-3513 406
@gammazero 84 +5719/-2815 374
@MarcoPolo 24 +1275/-311 58
@guillaumemichel 14 +392/-967 41
@hsanjuan 4 +1093/-43 15
@sneaxhuh 2 +840/-19 7
@cortze 1 +367/-35 2
@schomatis 1 +288/-17 5
@rifeplight 1 +92/-195 18
@sukunrt 3 +22/-211 7
@2color 1 +207/-2 5
@djdv 8 +96/-65 10
@vlerdman 4 +90/-38 8
@v1rtl 1 +71/-3 2
@VedantMadane 1 +23/-8 4
@dozyio 1 +26/-4 2
@infrmtcs 1 +24/-1 2
@marten-seemann 1 +5/-1 2
@web3-bot 2 +3/-2 2
@MozirDmitriy 1 +4/-1 1
@aschmahmann 1 +2/-1 1
@willscott 1 +1/-1 1
@lbarrettanderson 1 +1/-1 1
@filipremb 1 +1/-1 1
Check out latest releases or
releases around ipfs/kubo v0.40.0

Don't miss a new kubo release

NewReleases is sending notifications on new releases.

Get notifications