# Persistence, permanence, and pinning

Understand the concepts behind IPFS pinning, along with the differences between persistence, permanence, and pinning.

# Persistence versus permanence

One goal of IPFS is to preserve humanity's history by letting users store data while minimising the risk of that data being lost or accidentally deleted. This is often referred to as permanence. But what does permanence really mean, and why does it matter?

A 2011 study found that the average lifespan of a web page is 100 days (opens new window) before it's gone forever. It's not good enough for the primary medium of our era to be this fragile. IPFS can keep every version of your file you wish to store, and make it simple to set up resilient networks for mirroring data.

Nodes on the IPFS network can automatically cache resources they download, and keep those resources available for other nodes. This system depends on nodes being willing and able to cache and share resources with the network. Storage is finite, so nodes need to clear out some of their previously cached resources to make room for new resources. This process is called garbage collection.

To ensure that data persists on IPFS, and is not deleted during garbage collection, data can be pinned to one or more IPFS nodes. Pinning gives you control over disk space and data retention. As such, you should use that control to pin any content you wish to keep on IPFS indefinitely.

# Garbage Collection

Garbage collection (opens new window) is a form of automatic resource management widely used in software development. The garbage collector attempts to reclaim memory occupied by objects that are no longer in use. IPFS uses garbage collection to free disk space on your IPFS node by deleting data that it thinks is no longer needed.

The IPFS garbage collector is configured in the Datastoresection of the go-ipfs config file (opens new window). The important settings related to the garbage collector are:

  • StorageGCWatermark: The percentage of the StorageMax value at which a garbage collection will be triggered automatically, if the daemon is running with automatic garbage collection enabled. The default is 90`.

  • GCPeriod: Specify how frequently garbage collection should run. Only used if automatic garbage collection is enabled. The default is 1 hour.

To manually start garbage collection, run ipfs repo gc:

ipfs repo gc

> removed QmPZhyTu8D7NqR5NvgkgNYsSYD4CNjnyuFejB8i23itJvA
> removed QmSYQFVAZgEnpa6NxiW5agyj3XU9VR4CbERShXiLhuPPPE
> removed QmS6SJXApoi59hqD8Naktgakc6UNHK1XDhqhtMg9sBhY8g

To enable automatic garbage collection use --enable-gc when starting the IPFS daemon:

ipfs daemon --enable-gc

> Initializing daemon...
> go-ipfs version: 0.9.0
> Repo version: 10
> ...


If you use IPFS Desktop, you can trigger garbage collection by clicking on the taskbar icon of the IPFS Desktop application and selecting AdvancedRun Garbage Collector.

# Pinning in context

An IPFS node can protect data from garbage collection based on different kinds of user events.

  • The universal way is by adding a low-level local pin. This works for all data types and can be done manually, but if you add a file using the CLI command ipfs add, your IPFS node will automatically pin that file for you.
  • When working with files and directories, a better way may be to add them to the local Mutable File System (MFS). This protects the data from garbage collection in the same way as local pinning, but is somewhat easier to manage.


If you want to learn more about how pinning fits into the overall lifecycle of data in IPFS, check out the course from IPFS Camp The Lifecycle of Data in DWeb (opens new window).

# Pinning services

To ensure that your important data is retained, you may want to use a pinning service. These services run lots of IPFS nodes and allow users to pin data on those nodes for a fee. Some services offer free storage-allowance for new users. Pinning services are handy when:

  • You don't have a lot of disk space, but you want to ensure your data sticks around.
  • Your computer is a laptop, phone, or tablet that will have intermittent connectivity to the network. Still, you want to be able to access your data on IPFS from anywhere at any time, even when the device you added it from is offline.
  • You want a backup that ensures your data is always available from another computer on the network if you accidentally delete or garbage-collect your data on your own computer.

Some available pinning service providers are:

See how to work with remote pinning services.