What Is MFS in IPFS? The Mutable File System Explained

MFS in IPFS is the Mutable File System, a local file tree that lets you create, edit, move and delete files by path while IPFS recomputes the CIDs for you. Change one file, and its folder and the root get new CIDs too.

TL;DR:

• MFS puts paths such as /site/index.html on top of immutable IPFS data, and every edit produces a new root CID.
• MFS is not a pin: garbage collection keeps what MFS references, but ipfs pin ls won't list it and ipfs files rm never removes a pin.
• ipfs files cp /ipfs/<cid> fetches only the root block, so MFS protects only the blocks you already have.
• AIOZ Pin has no MFS feature, so you pin an MFS folder by its CID.

What Is MFS in IPFS?

IPFS data can't be edited in place, because a CID is derived from the bytes and every directory above a changed file needs a new CID as well. Rebuilding each parent node by hand is the content addressing trade-off in practice.

MFS does that bookkeeping for you. The IPFS docs say it lets you treat files "like you would a regular name-based filesystem", with "all the work of updating links and hashes taken care of for you". The files and folders underneath are ordinary UnixFS nodes, so a folder you build in MFS is a normal IPFS directory with a normal CID.

Three things follow from that design:

• It's local to your node. Kubo's help calls MFS "a single, dynamic filesystem mount" with one root CID, stored in the node's datastore next to your pins. Other peers can't list your MFS, and they can fetch a folder, file names included, only if they have its CID.
• Old versions keep their CIDs. The previous root CID still points at the previous tree until garbage collection removes blocks nothing references.
• It isn't limited to Kubo. Go code can use boxo/mfs, and JavaScript apps use @helia/mfs (8.0.9 on npm in October 2026).

Which ipfs files commands do you need?

Kubo's CLI reference, generated from the Kubo 0.43.1 help text, lists ten stable ipfs files subcommands plus three experimental ones. The commands below come from that help text, and we didn't run them because this machine has no IPFS binary.

# Make a folder and write a file into it
ipfs files mkdir -p /site
echo "hello world" | ipfs files write --create --parents /site/index.html

# Add a file from disk straight into MFS
ipfs add style.css --to-files /site/

# Look around, then reorganize
ipfs files ls /site
ipfs files read /site/index.html
ipfs files stat --hash /site    # the folder's current CID
ipfs files mv /site/index.html /site/home.html
ipfs files rm /site/home.html

Two of these behave differently from a normal disk, which can cost you time:

• ipfs files write builds a trickle DAG tuned for appends, and the help warns its CID "will be different from 'ipfs add'". Use ipfs add --to-files when you need the ipfs add CID; our post on why the same file can get different CIDs explains the wider cause.
• --flush defaults to true. Setting it to false speeds up big batches, but data may be lost if the daemon dies before ipfs files flush, and Kubo refuses new unflushed operations after Internal.MFSNoFlushLimit.

Does MFS pin your files?

No, but it protects them in a similar way, and that difference confuses people. In IPFS forum thread 16685, a user asked whether copying content into MFS pins it and whether ipfs files rm unpins it. Kubo's help text answers both:

• MFS content survives garbage collection: "All files and folders within MFS are respected and will not be deleted during garbage collections."
• MFS is separate from the pin set, so ipfs pin ls doesn't list MFS content and ipfs pin add or rm never touch it.
• Removing a path doesn't unpin: content you also pinned "will still remain pinned" after ipfs files rm.
• ipfs add pins by default but puts nothing in MFS unless you pass --to-files.

The IPFS pinning guide says things in MFS "are not pinned by default, but are protected from garbage-collection", so you can treat MFS as implicit pinning.

Lazy loading limits that protection. ipfs files cp /ipfs/<cid> /path fetches only the root block, and garbage collection can't keep blocks your node never downloaded. Kubo's help uses Wikipedia as the example: copying its root into MFS won't download Wikipedia, but it stops the parts you've read from being collected. If you want the whole thing on disk, fetch it too:

ipfs files cp /ipfs/<CID> /archive/dataset
ipfs pin add <CID>                           # fetches the full DAG and pins it
ipfs files stat --with-local /archive/dataset   # how much of it is local

Kubo v0.43.0 (August 3, 2026) fixed a related race. Before it, ipfs repo gc during MFS writes could delete blocks a write had added but not yet linked, leaving later ipfs files commands hanging. Our garbage collection explainer covers that fix, the pin types and when collection runs.

MFS, Pins and IPNS Side by Side

For a site you edit often, keep the files in MFS and publish the folder's CID under an IPNS name, so your links survive content changes. The static site hosting guide walks through the rest of that setup.

ipfs name publish /ipfs/$(ipfs files stat --hash /site)

If you narrow Kubo's Provide.Strategy from its default all, the values mfs and pinned+mfs announce MFS content, but only the blocks you have locally. Kubo re-announces those provider records every 22 hours by default.

How AIOZ Pin Handles It

AIOZ Pin doesn't have an MFS feature, and our docs don't mention MFS. That works out, because an MFS folder is just a CID. You can pin it by CID with POST https://api.aiozpin.network/api/pinning/pinByHash and hash_to_pin, or use the Pinning Service API from Kubo. These commands come from our docs and Kubo's help, and we didn't run them:

CID=$(ipfs files stat --hash /site)

# YOUR_JWT is the access token from the AIOZ Pin email login
ipfs pin remote service add pin https://api.aiozpin.network/api/psa/ YOUR_JWT
ipfs pin remote add --service=pin --name=site-v2 $CID
ipfs pin remote ls --service=pin --status=queued,pinning,failed

Kubo can also repin the MFS root for you. With the Policies.MFS setting on, Kubo sends a pin request when the root CID has changed, at most every 5 minutes by default. It replaces its earlier pin named policy/{PeerID}/mfs instead of adding a new one each time. The field is Enable in Kubo's source, although the docs heading says Enabled:

ipfs config --json Pinning.RemoteServices.pin.Policies.MFS.Enable true

We haven't tested this policy against our endpoint, so check the first repin with ipfs pin remote ls before you rely on it. Keep your node online until the pin reaches pinned, and if it sits in queued, read what each pin status means.

Next step: set up the endpoint from the AIOZ Pin Pinning Services API docs.

Frequently Asked Questions

What does MFS stand for in IPFS?

Mutable File System, a tool in IPFS implementations such as Kubo and Helia that lets you work with files by path while it updates the CIDs underneath.

Is adding a file to MFS the same as pinning it?

No. MFS content is protected from garbage collection, but it isn't in the pin set and ipfs pin ls won't show it.

Does ipfs files rm delete my data?

It removes the path, and the blocks stay until garbage collection runs, or longer if a pin or another MFS path still reaches them.

Can other people see my MFS folders?

No. MFS lives on your node, and others can fetch a folder only if they have its CID, for example because you shared it or published it under an IPNS name.

Can I pin an MFS folder on AIOZ Pin?

Yes, by its CID: read it with ipfs files stat --hash, then pin it by CID or through the Pinning Service API endpoint.

Related Reading

• Does Unpinning Delete a File on IPFS? Garbage Collection
• UnixFS: How IPFS Represents Files and Directories
• What Is IPNS? How IPFS Names Point to Changing Content
• Pin by CID on IPFS Without Re-Uploading Your Files
• IPFS Pinning Service API: What It Is, Why It Matters

References

• IPFS Docs: File systems
• Kubo CLI reference (0.43.1): ipfs files, ipfs add, ipfs pin ls
• IPFS Docs: Pin files
• IPFS Forums: How does ipfs files interact with pins?
• Kubo v0.43 changelog
• Kubo config docs: Pinning.RemoteServices and Provide.Strategy
• Kubo source: pinmfs.go and remotepin.go
• boxo/mfs package docs
• @helia/mfs README
• AIOZ Pin Docs: Pinning Services API
• AIOZ Pin Docs: Pinning