Multiaddr Format Change: /ipfs -> /p2p

[copied from the libp2p forums]

Libp2p is replacing all multiaddrs of the form /ipfs/QmFoo (old-style) with /p2p/QmFoo (new-style). The /ipfs prefix his an historical artifact from the days before libp2p was split out of IPFS.

All libp2p implementations have supported parsing new-style multiaddrs for at least 5 months (see the timeline). We are now entering the second phase of this transition and will:

  1. Deprecate the old-style (without removing support).
  2. Start formatting addresses using the new-style by default.


  • This change does not affect the network or binary representation of multiaddrs, just the textual representation.
  • This change will not affect network interoperability.
  • Old nodes (see below) will not be able to parse textual new-style multiaddrs. Specifically, ipfs swarm connect /p2p/QmFoobar will not work on go-ipfs releases before 0.4.16 or js-ipfs releases before 0.34.


Phase 1: Parsing Support

  • :white_check_mark: go-libp2p - June 26, 2018 (tag gx/v6.0.5)
  • :white_check_mark: go-ipfs - July 13, 2018 (0.4.16)
  • :white_check_mark: rust-libp2p - Since the beginning.
  • :white_check_mark: js-libp2p - April 12, 2019 (0.25.0)
  • :white_check_mark: js-ipfs - May 22, 2019 (0.36.0)

Phase 2: Default

  • :x: go-libp2p
  • :x: go-ipfs
  • :white_check_mark: rust-libp2p - always
  • :x: js-libp2p
  • :x: js-ipfs

@stebalien, just to be clear, this means that all IPFS production environments planning to add more nodes in the future(running latest versions of go-ipfs/js-ipfs) need to upgrade the go-ipfs/js-ipfs accordingly to address new nodes. Could you please confirm that?

Also, Is there a way to do this up-gradation with a zero downtime? Please advise.


No. This will not affect network communication or interoperability. It only affects the human readable (textual) multiaddr format.

Basically, ipfs commands will start returning addresses in the format /p2p/QmFoobar instead of /ipfs/QmFoobar. If you then try to use these addresses with, e.g., an ipfs swarm connect ... command on an old ipfs node (e.g., go-ipfs < 0.4.16), the command will fail.

1 Like

In summary, is the following true?

An IPFS node running on go-ipfs < 0.4.16 can indeed connect to another IPFS node running on go-ipfs > 0.4.16. It’s just that during the execution of the swarm connect command on the former node, you need to replace the /p2p/ with /ipfs/ manually, before passing it on.

Is my understanding correct?


Note: Interoperability with go-ipfs nodes <= 0.4.20 will likely break in the near future due to libp2p/go-libp2p#644 anyways. See the 0.4.21 release notes for details.

What about the /ipns prefix? Will it change as well?

@talb no. And /ipfs/QmFile isn’t changing either. This is specifically about multiaddrs.


  • /ipfs/Qm...: Either an IPFS file path or a libp2p multiaddr (machine address).
  • /ipns/Qm...: An IPNS file path.


  • /ipfs/Qm...: An IPFS file path.
    • ipfs cat /ipfs/Qm...
  • /p2p/Qm...: A multiaddr.
    • ipfs swarm connect /p2p/Qm...
  • /ipns/Qm...: An IPNS file path.
    • ipfs cat /ipns/Qm...

Note 1: Commands like ipfs swarm connect will continue to accept addresses of the form /ipfs/Qm... but this form has been deprecated.

Note 2: This confusion is the primary motivation for making this change.