What Is IPNS? How IPFS Names Point to Changing Content

What is IPNS? The InterPlanetary Name System gives IPFS content a name that stays the same while the CID behind it changes. The name is the hash of a public key, and whoever holds the matching private key publishes signed records that point the name at the current CID.

TL;DR:

• A CID changes whenever its content changes, so IPNS adds a stable name on top: a hash of a public key that points at whichever CID you last published
• A record carries a value, an expiry, a sequence number, a TTL, and a signature, so anyone can verify it without trusting whoever relayed it
• Kubo's config reference lists a 48-hour record lifetime and a 4-hour republish period as defaults, and a name stops resolving if nothing republishes it
• The private key is the name, so losing it means you can never update that name again
• DNSLink is faster and readable but depends on DNS, so pick it when you control a domain and update often

What Is IPNS and Why Does IPFS Need It?

A CID is derived from content, which is why it can verify what you receive. The same property makes it a poor address for anything that changes. A website, a dataset, or an NFT metadata file gets a new CID with every edit, and you would have to hand out the new one each time.

IPNS fixes that by naming something that does not change when the content does: a key, so you share one name and update where it points. The IPFS docs describe this as mutability on top of immutable data, and our article on why IPFS content cannot be edited in place covers the problem it solves.

How Does an IPNS Record Work?

An IPNS name is the hash of a public key, written as a CID with the libp2p-key codec. The record behind it holds the path it points to (usually /ipfs/<CID>) plus the fields the IPNS spec defines: a validity date, a sequence number, a TTL hint, and a V2 signature. The owner of the private key signs each record, and a client checks that signature against the name, so the record verifies itself. The same idea underlies how IPFS verifies content without trusting the gateway.

To update a name, you sign a new record with the same key. The sequence number marks the record's version, and Kubo's help text says a new one must be higher than the current record's. Ed25519 is the default key type in the spec, RSA remains for older names, and implementations must handle records up to 10 KiB.

Publishing and Resolving an IPNS Name

The examples below come from Kubo's built-in help for ipfs name, and I didn't run them because this machine has no IPFS binary (the ... is part of the help text).

# Publish an <ipfs-path> with your default name
ipfs name publish /ipfs/bafkreifjjcie6lypi6ny7amxnfftagclbuxndqonfipmb64f2km2devei4
# Published to k51qzi5uqu5dgklc20hksmmzhoy5lfrn5xcnryq6xp4r50b5yc0vnivpywfu9p: /ipfs/bafk...

# Publish with another name, added by an 'ipfs key' command
ipfs key gen --type=ed25519 mykey
ipfs name publish --key=mykey /ipfs/bafkreifjjcie6lypi6ny7amxnfftagclbuxndqonfipmb64f2km2devei4

# Resolve the value of your name, or of another name
ipfs name resolve
ipfs name resolve k51qzi5uqu5dlz49qkb657myg6f1buu6rauv8c6b489a9i1e4dkt7a3yo9j2wr

Without --key, Kubo signs with the self key, which is the key behind your node's PeerID. Gateways resolve names too: a request to /ipns/<name> returns the current content, although the IPFS docs note that resolving through a gateway means you trust that gateway's answer.

Records travel over the DHT by default, and the docs warn that publishing and resolving this way can be slow, especially the first time. IPNS over PubSub can speed updates up, but Kubo ships it disabled and marks it experimental (Ipns.UsePubsub).

How Long Does an IPNS Record Last?

Three timers decide how fresh a name is, and they are easy to mix up.

• Lifetime is how long a signed record stays valid. Kubo's config reference lists 48 hours as the default for Ipns.RecordLifetime, and the IPFS docs add that records in the DHT expire after 48 hours whatever their validity says.
• Republish period is how often your node signs and pushes the record again. The default for Ipns.RepublishPeriod is 4 hours, and Kubo refuses to start if that period exceeds the lifetime.
• TTL is how long a resolver may cache the answer before asking again. Kubo's help text gives 1 hour as the default for ipfs name publish --ttl and suggests 1 minute for quicker updates at the cost of more network load. Gateway operators can cap it with Ipns.MaxCacheTTL.

The practical result is that a name is only as available as the node that republishes it. If that node stays offline for more than 48 hours, the record expires and the name stops resolving. The IPFS docs frame the choice as consistency against availability: a short validity period keeps answers fresh, while a longer one survives outages better. If updates reach people slowly, the docs say to check the TTL first.

Provider records, which announce which node holds a block, follow a separate renewal cycle that this article on provider records covers.

Handling the Keys Behind a Name

Because the name is derived from the public key, the private key is the name. Whoever holds it can repoint the name, and if you lose it you can no longer publish updates. A different key means a different name, so there is no way to move an existing name to a new key.

Kubo creates one key per ipfs key gen, and the help text for ipfs key export shows how to back one up:

ipfs key export testkey --format=pem-pkcs8-cleartext -o privkey.pem

That output is an unencrypted private key, so store it like any other secret. For a site or dataset you intend to keep for years, use a dedicated key rather than self, so that rebuilding your node does not take the name with it.

Choosing Between IPNS and DNSLink

DNSLink maps a domain name to an IPFS path with a DNS TXT record. The IPFS docs say it is currently much faster than IPNS, uses human-readable names, and can also point to an IPNS name. Our DNSLink article goes deeper on the record, which lives at _dnslink.<your domain> and starts with dnslink=.

On 2026-10-16 I ran the lookup that the DNSLink docs use for docs.ipfs.tech:

dig +noall +answer TXT _dnslink.docs.ipfs.tech
# _dnslink.docs.ipfs.tech. 3600 IN CNAME _dnslink.docs-ipfs-tech.dnslinks.ipshipyard.tech.
# _dnslink.docs-ipfs-tech.dnslinks.ipshipyard.tech. 300 IN TXT "dnslink=/ipfs/bafybeier6ud42ptljtfaxrdlknktw54b7ohfpg5h33mosxpxjndxs7xzvm"

The CID differs from the one printed on the docs page, so the record has moved on since that page was written. The answer also arrives through a CNAME, so the site owner can change the TXT record without touching the main zone.

The docs do not say when to choose each, so this is my reading. Pick DNSLink when you own a domain, want a readable address, and update often. Pick IPNS when you have no domain, or when you want the name controlled by a key instead of a registrar. You can combine them: point a DNSLink record at an IPNS name, then update only the IPNS record. The trust model differs as well: DNSLink relies on DNS for the mapping, while an IPNS record proves itself with its signature.

IPNS and AIOZ Pin

AIOZ Pin pins CIDs, and the docs I read don't mention IPNS, so treat it as something you run yourself on top of pinned content. Pin the new CID first, then publish the record, so the name never points at content nobody holds. The previous version stays pinned until you unpin it, and what unpinning does explains what happens next.

Frequently Asked Questions

What is the difference between IPNS and a CID?

A CID names fixed content and changes when the content does. An IPNS name stays the same and points at a CID that you can change.

Is IPNS the same as DNSLink?

No. IPNS uses a name derived from a key and a signed record. DNSLink uses a DNS TXT record on a domain you control, and it can point at an IPFS path or an IPNS name.

Why does my IPNS name stop resolving?

Usually the record expired because nothing republished it, since Kubo defaults to a 48-hour lifetime and a 4-hour republish period and a node offline for longer than 48 hours loses the record.

Can anyone publish to my IPNS name?

No. Only the holder of the private key can sign a valid record for the name, and resolvers reject records with a bad signature.

Is IPNS fast?

Not always, because the IPFS docs warn that publishing and resolving over the DHT can be slow, especially the first time, while DNSLink is currently much faster.

Does AIOZ Pin manage IPNS names?

The docs I read don't mention IPNS, and AIOZ Pin pins by CID, so run IPNS yourself and pin each new CID before you publish it.

Related Reading

• How IPFS Verifies Content Without Trusting the Gateway - the same signature check, applied to names
• IPFS Immutability: Why You Can't Edit a File in Place - the problem IPNS works around
• DNSLink: Pointing a Domain Name at IPFS Content - the other way to get a stable name
• Why IPFS Provider Records Expire and Get Renewed - a different expiry cycle that people confuse with IPNS
• How to Host a Static Website on IPFS (and Why Pin It) - where a stable name matters most

References

• IPFS Docs: IPNS
• IPFS Docs: DNSLink
• IPNS Record and Protocol specification
• Kubo configuration reference: Ipns
• Kubo CLI help source: ipfs name