Does Unpinning Delete a File on IPFS? Garbage Collection

No, unpinning a file on IPFS does not delete it. Unpinning removes the protection on its blocks, and they stay on disk until garbage collection runs on that node. Any other node that pinned the same CID keeps serving it, so the file can stay online after you unpin.

TL;DR:

• ipfs pin rm takes the pin away so the blocks can be garbage collected if needed; it deletes nothing by itself
• ipfs repo gc is what frees disk space, and it removes every local block that no pin and no MFS file still reaches
• Kubo only collects garbage on its own when the daemon runs with --enable-gc, which is off by default
• Local pins live on your node, while remote pins live on a pinning service, and removing one never touches the other
• On AIOZ Pin you unpin by pin ID (DELETE /api/pinning/unpin/{pinId}), and copies pinned by anyone else stay online

Updated Oct 19, 2026: new question-form title, the ipfs pin ls, pin rm and repo gc examples from the Kubo docs, a local vs remote pinning section, and a diagram.

What Does Unpinning Do on IPFS?

A pin is a "keep this" mark on blocks your node already stores, not a second copy of them. The Kubo help for ipfs pin rm describes it as removing the pin "allowing it to be garbage collected if needed", and by default it unpins recursively. Until the next garbage collection, the blocks are still on your disk and you can pin them again for free.

Here is the example from the Kubo help for ipfs pin ls, which adds a file, unpins it and pins it again directly. We don't have an IPFS binary on this machine, so this is the documented output, not a run of our own:

$ echo "hello" | ipfs add -q
QmZULkCELmmk5XNfCgTnCyFgAVxBRBXyDHGGMVoLFLiXEN
$ ipfs pin ls
QmZULkCELmmk5XNfCgTnCyFgAVxBRBXyDHGGMVoLFLiXEN recursive
# now remove the pin, and repin it directly
$ ipfs pin rm QmZULkCELmmk5XNfCgTnCyFgAVxBRBXyDHGGMVoLFLiXEN
unpinned QmZULkCELmmk5XNfCgTnCyFgAVxBRBXyDHGGMVoLFLiXEN
$ ipfs pin add -r=false QmZULkCELmmk5XNfCgTnCyFgAVxBRBXyDHGGMVoLFLiXEN
pinned QmZULkCELmmk5XNfCgTnCyFgAVxBRBXyDHGGMVoLFLiXEN directly
$ ipfs pin ls --type=direct
QmZULkCELmmk5XNfCgTnCyFgAVxBRBXyDHGGMVoLFLiXEN direct

Notice the first ipfs pin ls line says recursive. The IPFS persistence docs explain why: when you add a file with ipfs add, your node pins it for you.

The Three Pin Types

Kubo lists three pin types, and you can filter by each one with ipfs pin ls --type. A direct pin protects one block and nothing it links to, so a directly pinned folder root does not protect the files inside it.

A recursive pin protects a block and everything below it, which is what you almost always want for a file or a folder. An indirect pin is one you never asked for: the Kubo help calls it "pinned indirectly by an ancestor (like a refcount)".

That last type explains a common error. The ipfs pin rm command can't remove a pin that is only indirect, and the help tells you to check with ipfs pin ls -t indirect <cid>. To free that block, you remove the recursive pin on its ancestor instead.

When Does IPFS Garbage Collection Run?

Only when something triggers it. The manual trigger is ipfs repo gc, which the Kubo help says will "sweep the local set of stored objects and remove ones that are not pinned" to reclaim disk space.

Automatic collection is opt-in, and the Kubo config docs say it needs the daemon started with --enable-gc, and that option defaults to false. With it on, Kubo runs garbage collection every Datastore.GCPeriod (default 1h). It also runs one when the repo reaches Datastore.StorageGCWatermark, 90% of StorageMax by default.

Pins are not the only thing that protects blocks. The IPFS persistence docs say files in the Mutable File System (MFS) are protected "in the same way as local pinning", so whatever you keep in ipfs files survives a sweep. Popularity, age and links from other nodes don't count, because GC only checks what your own pins and MFS reach.

If you run your own node, the MFS part has a recent fix. Kubo v0.43.0 (August 3, 2026) stopped ipfs repo gc from deleting blocks that an MFS write had added but not yet linked. Before the fix, that race could leave every later ipfs files command hanging until you force-killed the daemon. Kubo now takes the same lock ipfs add uses around each MFS change and reads the MFS root while holding it.

Local vs Remote Pinning

A local pin lives in your node's pin set and protects blocks on your disk. A remote pin is a request to a pinning service, made through the IPFS Pinning Service API, asking the service to keep the CID on its own nodes. The two are independent: ipfs repo gc on your laptop never removes a remote pin, and removing a remote pin never deletes your local blocks.

AIOZ Pin supports the Pinning Service API at https://api.aiozpin.network/api/psa/. Its docs show these Kubo commands, where YOUR_JWT is the access token from the email login:

ipfs pin remote service add pin https://api.aiozpin.network/api/psa/ YOUR_JWT
ipfs pin remote add --service=pin --name=my-file QmYourCIDHere
ipfs pin remote ls --service=pin
ipfs pin remote ls --service=pin --status=queued,pinning,failed

Kubo also has ipfs pin remote rm, which "removes remote pins, allowing them to be garbage-collected if needed". Its help suggests you run ls with the same query first, and it asks for --force when several pins match. The AIOZ Pin PSA page shows add and ls but doesn't list rm, so the native unpin call below is the documented way to remove a pin.

Is the File Gone From the Network After You Unpin?

Only if nobody else holds it, because a CID names the content itself and any node that has the blocks can serve them. Unpinning on your node, or on one pinning service, changes nothing on the other nodes that pinned or cached the same CID.

If you want a file to stay online, a pin on a service you pay for is the only part you control. If you want a file gone, unpinning everywhere you control is the limit of what you can do, because you can't recall copies other people pinned.

How AIOZ Pin Handles It

On AIOZ Pin you unpin by the pin's ID, not by its CID. Every pin response includes an id next to the cid, and the Pinning API removes the pin with one call:

DELETE https://api.aiozpin.network/api/pinning/unpin/{pinId}

The CLI on our SDKs page does the same with pinning unpin --id=<pin-id>, and the Node.js SDK has unpin('file-id'). To find an ID, list your pins with GET /api/pinning/pins/, which accepts pinned=all, true or false and returns a date_unpinned field for each record.

What the docs don't cover yet: how soon unpinned blocks leave our nodes, and how an unpin shows up in the daily storage charge on the payment page. For the request format, see the AIOZ Pin Pinning API page.

Frequently Asked Questions

Does unpinning a file on IPFS delete it immediately? No. The blocks stay on disk until garbage collection runs on that node, and only if no other pin or MFS file still reaches them.

Does IPFS garbage collection run automatically? Only if the Kubo daemon was started with --enable-gc, which is off by default. Otherwise it runs when you call ipfs repo gc.

Why can't I remove a pin with ipfs pin rm? The block is probably pinned indirectly by a recursive pin on an ancestor. Check with ipfs pin ls -t indirect <cid> and unpin the ancestor.

Can I get a file back after I unpin it? Yes, if garbage collection hasn't run yet, because the blocks are still on disk and pinning the CID again costs nothing. After GC, you need a node that still has the file.

Does MFS protect files the same way pinning does? Yes. The IPFS docs say MFS protects data from garbage collection the same way a local pin does, and it is easier to manage for files and folders.

If I unpin a file on AIOZ Pin, does it disappear from IPFS? Only if no other node has it pinned or cached. Unpinning ends our pin for your account and has no effect on copies elsewhere.

Related Reading

• AIOZ Pin Wallet: How AIOZ Token Deposits Become Credit - the account-level version of the same question
• AIOZ Pin CLI Tutorial: Login, Pin, List, and Unpin Files - the unpin command with every flag
• IPFS Pinning Service API: What It Is, Why It Matters - the standard behind remote pins
• IPFS Pin Stuck on Pinning? What Each Pin Status Means - the statuses a remote pin moves through
• IPFS Content Addressing vs. Location Addressing - why pinning has to exist at all
• Content Moderation on IPFS: What Happens to Removed Content - why unpinning can't recall other copies

References

• Kubo CLI reference: ipfs pin ls, pin rm, repo gc and pin remote
• IPFS Docs: Persistence, Permanence, and Pinning
• Kubo config docs: Datastore.GCPeriod and StorageGCWatermark
• Kubo v0.43.0 release notes
• AIOZ Pin docs: Pinning Services API