Get Started

IPFS is a distributed system for storing and accessing files, websites, applications, and data.

Decentralization

Making it possible to download a file from many locations that aren’t managed by one organization…

- Supports a resilient internet. If someone attacks Wikipedia’s web servers or an engineer at Wikipedia makes a big mistake that causes their servers to catch fire, you can still get the same webpages from somewhere else.

- Makes it harder to censor content. Because files on IPFS can come from many places, it’s harder for anyone (whether they’re states, corporations, or someone else) to block things. In 2017, Turkey blocked Wikipedia and Spain blocked access to sites related to the Catalonian independence movement. We hope IPFS can help provide ways to circumvent actions like these when they happen.

- Can speed up the web when you’re far away or disconnected. If you can retrieve a file from someone nearby instead of hundreds or thousands of miles away, you can often get it faster. This is especially valuable if your community is networked locally, but doesn’t have a good connection to the wider internet. (Well-funded organizations with technical expertise do this today by using multiple data centers or CDNs — content distribution networks. IPFS hopes to make this possible for everyone.)

That last point is actually where IPFS gets its full name: the InterPlanetary File System. We’re striving to build a system that works across places as disconnected or as far apart as planets. While that's an idealistic goal, it keeps us working and thinking hard, and most everything we create in pursuit of that goal is also useful here at home.

Content Addressing

What do links on IPFS look like:

/ipfs/QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco/wiki/Example.html

That jumble of letters after /ipfs/ is called a content identifier and it’s how IPFS can get content from multiple places.

Traditional URLs and file paths such as…

  • https://en.wikipedia.org/wiki/Aardvark
  • /Users/Alice/Documents/term_paper.doc
  • C:\Users\Joe\My Documents\project_sprint_presentation.ppt

Instead of being location-based, IPFS addresses a file by what’s in it, or by its content. The content identifier above is a cryptographic hash of the content at that address. The hash is unique to the content that it came from, even though it may look short compared to the original content. It also allows you to verify that you got what you asked for — bad actors can’t just hand you content that doesn’t match. (If hashes are new to you, check out the concept guide on hashes for an introduction.)

Because the address of a file in IPFS is created from the content itself, links in IPFS can’t be changed. For example ...

  • If the text on a web page is changed, the new version gets a new, different address.
  • Content can’t be moved to a different address. On today’s internet, a company could reorganize content on their website and move a page at http://mycompany.com/what_we_do to http://mycompany.com/services. In IPFS, the old link you have would still point to the same old content.

If you're command-line savvy and just want to get up and running with IPFS right away, follow this quick start guide. Please note that this guide assumes that you'll be installing go-ipfs, the reference implementation written in Go.

TIP Don’t want to use the command line right now? Give the desktop-app implementation of IPFS a try. It also does all the steps listed on this page automatically, so you can run IPFS from the terminal later whenever you want. Download IPFS Desktop.

Install IPFS

Installing IPFS is simple, but varies between operating system:

Windows
  1. Download go-ipfs_v0.5.1_windows-386.zip from GitHub
  2.               cd ~\
                  wget https://github.com/ipfs/go-ipfs/releases/download/v0.5.1/go-ipfs-v0.5.1_windows-386.zip -Outfile go-ipfs-v0.5.1.zip
                
  3. Unzip the file and move it somewhere handy.
  4. Expand-Archive -Path go-ipfs-v0.5.1.zip -DestinationPath ~\Apps\go-ipfs_v0.5.1
  5. Move into the go-ipfs_v0.5.1 folder and check that the ipfs.exe works:
  6.               cd ~\Apps\go-ipfs_v0.5.1\go-ipfs
                  .\ipfs.exe --version 
                  > ipfs version 0.5.0
                

    While you can use IPFS right now, it's better to add ipfs.exe to your PATH.

  7. Print the current working directory and copy it to your clipboard:
  8.               pwd
    
                  > Path
                  > ----
                  > C:\Users\Johnny\Apps\go-ipfs_v0.5.1\go-ipfs
                
  9. Add the address you just copied to PowerShell's PATH by adding it to the end of the profile.ps1 file stored in Documents\WindowsPowerShell:
  10.               Add-Content C:\Users\Johnny\Documents\WindowsPowerShell\profile.ps1 "[System.Environment]::SetEnvironmentVariable('PATH',`$Env:PATH+';;C:\Users\Johnny\Apps\go-ipfs_v0.5.1\go-ipfs')"
                
  11. Close and reopen your PowerShell window. Test that your IPFS path is set correctly by going to your home folder and asking IPFS for the version:
  12.               cd ~
                  ipfs --version
                  > ipfs version 0.5.0
                
macOS
  1. Download go-ipfs_v0.5.1_darwin-386.tar.gz from GitHub.
  2.               wget https://github.com/ipfs/go-ipfs/releases/download/v0.5.1/go-ipfs_v0.5.1_darwin-amd64.tar.gz
                
  3. Unzip the file:
  4.               tar -xvzf go-ipfs_v0.5.1_darwin-amd64.tar.gz
    
                  > x go-ipfs/install.sh
                  > x go-ipfs/ipfs
                  > x go-ipfs/LICENSE
                  > x go-ipfs/LICENSE-APACHE
                  > x go-ipfs/LICENSE-MIT
                  > x go-ipfs/README.md
                
  5. Move into the go-ipfs folder and run the install script:
  6.               bash install.sh
    
                  > Moved ./ipfs to /usr/local/bin
                
  7. Check that IPFS install properly:
  8.               ipfs --version
    
                  > ipfs version 0.5.0
                
Linux
  1. Download go-ipfs_v0.5.1_linux-amd64.tar.gz from GitHub
  2.               wget https://github.com/ipfs/go-ipfs/releases/download/v0.5.1/go-ipfs_v0.5.1_linux-amd64.tar.gz
                
  3. Unzip the file:
  4.               tar -xvzf go-ipfs_v0.5.1_linux-amd64.tar.gz
    
                  > x go-ipfs/install.sh
                  > x go-ipfs/ipfs
                  > x go-ipfs/LICENSE
                  > x go-ipfs/LICENSE-APACHE
                  > x go-ipfs/LICENSE-MIT
                  > x go-ipfs/README.md
                
  5. Move into the go-ipfs folder and run the install script:
  6.               cd go-ipfs
                  sudo bash install.sh
    
                  > Moved ./ipfs to /usr/local/bin
                
  7. Test that IPFS has installed correctly:
  8.               ipfs --version
    
                  > ipfs version 0.5.0
                

Initialize the Repository

ipfs stores all its settings and internal data in a directory called the repository. Before using IPFS for the first time, you’ll need to initialize the repository with the ipfs init command:

            ipfs init
            > initializing ipfs node at /Users/jbenet/.go-ipfs
            > generating 2048-bit RSA keypair...done
            > peer identity: Qmcpo2iLBikrdf1d6QU6vXuNb6P7hwrbNPW9kLAH8eG67z
            > to get started, enter:
            >
            >   ipfs cat /ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/readme
          

If you are running on a server in a data center, you should initialize IPFS with the server profile. Doing so will prevent IPFS from creating a lot of data center-internal traffic trying to discover local nodes:

            ipfs init --profile server
          

The hash after peer identity: is your node’s ID and will be different from the one shown in the above output. Other nodes on the network use it to find and connect to you. You can run ipfs id at any time to get it again if you need it.

Now, try running the command suggested to you in the output of ipfs init. The one that looks like ipfs cat /ipfs//readme.

You should see something like this:

            Hello and Welcome to IPFS!

            ██╗██████╗ ███████╗███████╗
            ██║██╔══██╗██╔════╝██╔════╝
            ██║██████╔╝█████╗  ███████╗
            ██║██╔═══╝ ██╔══╝  ╚════██║
            ██║██║     ██║     ███████║
            ╚═╝╚═╝     ╚═╝     ╚══════╝

            If you see this, you have successfully installed
            IPFS and are now interfacing with the ipfs merkledag!

             -------------------------------------------------------
            | Warning:                                              |
            |   This is alpha software. use at your own discretion! |
            |   Much is missing or lacking polish. There are bugs.  |
            |   Not yet secure. Read the security notes for more.   |
             -------------------------------------------------------

            Check out some of the other files in this directory:

            ./about
            ./help
            ./quick-start     <-- usage examples
            ./readme          <-- this file
            ./security-notes
          

You can explore other objects in the repository. In particular, the quick-start directory which shows example commands to try:

ipfs cat /ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/quick-start

Take your node online

Once you're ready to join your node to the public network, run the ipfs daemon in another terminal and wait for all three lines below to appear to know that your node is ready:

            ipfs daemon
            > Initializing daemon...
            > API server listening on /ip4/127.0.0.1/tcp/5001
            > Gateway server listening on /ip4/127.0.0.1/tcp/8080
          

Make a note of the TCP ports you receive. If they are different, use yours in the commands below.

Now, switch back to your original terminal. If you’re connected to the network, you should be able to see the ipfs addresses of your peers when you run:

            ipfs swarm peers
            > /ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ
            > /ip4/104.236.151.122/tcp/4001/p2p/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx
            > /ip4/134.121.64.93/tcp/1035/p2p/QmWHyrPWQnsz1wxHR219ooJDYTvxJPyZuDUPSDpdsAovN5
            > /ip4/178.62.8.190/tcp/4002/p2p/QmdXzZ25cyzSF99csCQmmPZ1NTbWTe8qtKFaZKpZQPdTFB
          

These are a combination of /p2p/.

Now, you should be able to get objects from the network. Try:

            ipfs cat /ipfs/QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ/cat.jpg > cat.jpg
            open cat.jpg
          

Next, try sending objects to the network, and then viewing it in your favorite browser. The example below uses curl as the browser, but you can open the IPFS URL in other browsers as well:

            hash=`echo "I <3 IPFS -$(whoami)" | ipfs add -q`
            curl "https://ipfs.io/ipfs/$hash"
            > I <3 IPFS -
          

The gateway served a file from your computer. The gateway queried the Distributed hash table (DHT), found your machine, requested the file, your computer sent it to the gateway, and the gateway sent it to your browser.

You can also check it out at your own local gateway:

            curl "http://127.0.0.1:8080/ipfs/$hash"
            > I <3 IPFS -
          

Web Console

You can view the web console on your local node by going to localhost:5001/webui. This should bring up a console like this:

IPFS Companion

While we are at it, IPFS Companion is a browser extension that simplifies access to IPFS resources and adds support for the IPFS protocol.

It will automatically redirect IPFS gateway requests to your local daemon so that you are not relying on or trusting, remote gateways.

It runs in Firefox (desktop and Android) and various Chromium-based browsers such as Google Chrome or Brave. Check out its features and install it today!

A great way to get to know IPFS is to use it to host a simple, single-page website. Here's a step-by-step guide to doing just that.

Create Your Site

Assume you have a static website in a directory mysite.

In order to publish it as a site, install IPFS and make sure your IPFS daemon is running:

            $ ipfs daemon
          

Then add the directory with your website:

            $ ls mysite
            img index.html
            $ ipfs add -r mysite
            added QmcMN2wqoun88SVF5own7D5LUpnHwDA6ALZnVdFXhnYhAs mysite/img/spacecat.jpg
            added QmS8tC5NJqajBB5qFhcA1auav14iHMnoMZJWfmr4k3EY6w mysite/img
            added QmYh6HbZhHABQXrkQZ4aRRSoSa6bb9vaKoHeumWex6HRsT mysite/index.html
            added QmYeAiiK1UfB8MGLRefok1N7vBTyX8hGPuMXZ4Xq1DPyt7 mysite/
          

The last hash, next to the folder name, mysite/ is the one to remember, call it $SITE_CID for now.

You can test it out locally by opening http://localhost:8080/ipfs/$SITE_CID in a browser or with wget or curl from the command line.

To view it from another ipfs node, you can try http://gateway.ipfs.io/ipfs/$SITE_CID in a browser. This will work from a browser on another device, inside or outside the network where you added the site's file.

Those hashes are difficult to remember. Let's look at some ways to get rid of them.

Edit your DNS records

Assume you have the domain name your.domain and can access your registrar's control panel to manage DNS entries for it.

Create a DNS TXT record (DNSLink), with the key your.domain. and the value dnslink=/ipfs/$SITE_CID where $SITE_CID is the value from the section above.

Once you've created that record, and it has propagated you should be able to find it.

            $ dig +noall +answer TXT your.domain
            your.domain.            60      IN      TXT     "dnslink=/ipfs/$SITE_CID"
          

Now you can view your site at http://localhost:8080/ipns/your.domain.

You can also try this on the gateway at http://gateway.ipfs.io/ipns/your.domain.

Use IPNS

Each time you change your website, you will have to republish it, update the DNS TXT record with the new value of $SITE_CID and wait for it to propagate.

You can get around that limitation by using IPNS, the InterPlanetary Naming System.

You might have noticed /ipns/ instead of /ipfs/ in the updated links in the previous section.

The IPNS is used for mutable content in the IPFS network. It's relatively easy to use, and will allow you to change your website without updating the dns record every time.

To enable the IPNS for your content, run the following command, where $SITE_CID is the hash value from the first step.

            $ ipfs name publish $SITE_CID
            Published to $PEER_ID: /ipfs/$SITE_CID
          

You will need to note and save that value of $PEER_ID for the next steps.

Load the urls http://localhost:8080/ipns/$PEER_ID and http://gateway.ipfs.io/ipns/$PEER_ID to confirm this step.

Return to your registrar's control panel, change the DNS TXT record with the key of your.domain to dnslink=/ipns/$PEER_ID, wait for that record to propagate, and then try the urls http://localhost:8080/ipns/your.domain and http://gateway.ipfs.io/ipns/your.domain.

Note: When using IPNS to update websites, assets may be loaded from two different resolved hashes while the update propagates. This may result in outdated URLs or missing assets until the update has completely propagated.

Point your domain to IPFS

You now have a website on ipfs/ipns, but your visitors can't access it at http://your.domain.

What we can do is have requests for http://your.domain resolved by an IPFS gateway daemon.

Return to your registrar's control panel and add an A record with key of your.domain and value of the IP address of an ipfs daemon that listens on port 80 for HTTP requests (such as gateway.ipfs.io). If you don't know the IP address of the daemon you plan to use, you can find it using the command like:

$ nslookup gateway.ipfs.io
  • Note the IP addresses returned.
  • Create an A record for each IPv4 address (e.g. 209.94.90.1 for ipfs.io).
  • Create an AAAA record for each IPv6 address (e.g. use 2602:fea2:2::1 for ipfs.io).

Note: The ipfs.io gateway IP addresses won't change, so you can set them and forget them. If you use a custom gateway where you don't control the IP address and they could change you may need to re-check them periodically and update your DNS records if they do.

Visitors' browsers will send your.domain in the Host header of their requests. The ipfs gateway will recognize your.domain, look up the value of the DNS TXT for your domain, then serve the files in /ipns/your.domain/ instead of /.

If you point your.domain's A and AAAA record to the IP addresses of gateway.ipfs.io, and then wait for the DNS to propagate, then anyone should be able to access your ipfs-hosted site without any extra configuration at http://your.domain.

Use CNAMEs

Alternatively, it is possible to use CNAME records to point at the DNS records of the gateway. This way, IP addresses of the gateway are automatically updated.

However you will need to change the key for the TXT record from your.domain to _dnslink.your.domain.

So by creating a CNAME for your.domain to gateway.ipfs.io and adding a _dnslink.your.domain record with dnslink=/ipns/ you can host your website without explicitly referring to IP addresses of the ipfs gateway.