kubo Documentation

IPFS implementation in Go: a daemon that stores and serves content-addressed data, with a CLI, HTTP Gateway, and RPC API

17,093 stars Go Go 1 file ยท ~19,444 tokens #ipfs
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy kubo on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name kubo -p 4001:4001 --restart always ipfs/kubo:latest
Configured Services & Ports
โš™๏ธ ipfs
image: build locally
๐Ÿ”Œ Ports: 4001:4001/tcp, 4001:4001/udp, 127.0.0.1:5001:5001, 127.0.0.1:8080:8080
docker-compose.yml
yaml (docker-compose.yml) 
version: '3.8'
services:
  ipfs:
    build: .
    restart: unless-stopped
    volumes:
      - ipfs_path:/data/ipfs
      - ipfs_fuse:/ipfs
      - ipns_fuse:/ipns
    environment:
      - IPFS_PATH=/data/ipfs
    ports:
      # Swarm listens on all interfaces, so is remotely reachable.
      - 4001:4001/tcp
      - 4001:4001/udp
      
      # The following ports only listen on the loopback interface, so are not remotely reachable by default.
      # If you want to override these or add more ports, see https://docs.docker.com/compose/extends/ .
      
      # API port, which includes admin operations, so you probably don't want this remotely accessible.
      - 127.0.0.1:5001:5001
      
      # HTTP Gateway
      - 127.0.0.1:8080:8080
volumes:
  ipfs_path:
  ipfs_fuse:
  ipns_fuse:

1. Project Overview & Quickstart (ipfs/kubo)

File: README.md

Kubo: IPFS Implementation in Go

What is Kubo?

Kubo was the first IPFS implementation and is the most widely used one today. It takes an opinionated approach to content-addressing (CIDs, DAGs) that maximizes interoperability: UnixFS for files and directories, HTTP Gateways for web browsers, Bitswap and HTTP for verifiable data transfer.

Features:

Other IPFS implementations: Helia (JavaScript), more...

Quick Taste

After installing Kubo, verify it works:

console
$ ipfs init
generating ED25519 keypair...done
peer identity: 12D3KooWGcSLQdLDBi2BvoP8WnpdHvhWPbxpGcqkf93rL2XMZK7R

$ ipfs daemon &
Daemon is ready

$ echo "hello IPFS" | ipfs add -q --cid-version 1
bafkreicouv3sksjuzxb3rbb6rziy6duakk2aikegsmtqtz5rsuppjorxsa

$ ipfs cat bafkreicouv3sksjuzxb3rbb6rziy6duakk2aikegsmtqtz5rsuppjorxsa
hello IPFS

Verify this CID is provided by your node to the IPFS network: https://check.ipfs.network/?cid=bafkreicouv3sksjuzxb3rbb6rziy6duakk2aikegsmtqtz5rsuppjorxsa

See ipfs add --help for all import options. Ready for more? Follow the command-line quick start.

Install

Follow the official installation guide, or choose: prebuilt binary | Docker | package manager | from source.

Prefer a GUI? Try IPFS Desktop and/or IPFS Companion.

Minimal System Requirements

Kubo runs on most Linux, macOS, and Windows systems. For optimal performance, we recommend at least 6 GB of RAM and 2 CPU cores (more is ideal, as Kubo is highly parallel).

[!IMPORTANT]
Larger pinsets require additional memory, with an estimated ~1 GiB of RAM per 20 million items for reproviding to the Amino DHT.

[!CAUTION]
Systems with less than the recommended memory may experience instability, frequent OOM errors or restarts, and missing data announcement (reprovider window), which can make data fully or partially inaccessible to other peers. Running Kubo on underprovisioned hardware is at your own risk.

For running Kubo on constrained hardware such as a Raspberry Pi, see Kubo on low-memory devices.

Official Prebuilt Binaries

Download from https://dist.ipfs.tech#kubo or GitHub Releases.

Docker

Official images are published at https://hub.docker.com/r/ipfs/kubo/:

๐ŸŸข Release Images

Use these for production deployments.

console
$ docker pull ipfs/kubo:latest
$ docker run --rm -it --net=host ipfs/kubo:latest

To customize your node, pass config via -e or mount scripts in /container-init.d.

๐ŸŸ  Developer Preview Images

For internal testing, not intended for production.

๐Ÿ”ด Internal Staging Images

For testing arbitrary commits and experimental patches (force push to staging branch).

Build from Source

bash
git clone https://github.com/ipfs/kubo.git
cd kubo
make build    # creates cmd/ipfs/ipfs
make install  # installs to $GOPATH/bin/ipfs

See the Developer Guide for details, Windows instructions, and troubleshooting.

Package Managers

Kubo is available in community-maintained packages across many operating systems, Linux distributions, and package managers. See Repology for the full list:

[!WARNING]
These packages are maintained by third-party volunteers. The IPFS Project and Kubo maintainers are not responsible for their contents or supply chain security. For increased security, build from source.

Linux

Distribution Install Version
Ubuntu PPA: sudo apt install ipfs-kubo
Arch pacman -S kubo
Fedora COPR: dnf install kubo
Nix nix-env -i kubo
Gentoo emerge -a net-p2p/kubo
openSUSE zypper install kubo
Solus sudo eopkg install kubo
Guix guix install kubo
other See Repology for the full list

Snap no longer supported (#8688)

macOS

Manager Install Version
Homebrew brew install ipfs
MacPorts sudo port install ipfs
Nix nix-env -i kubo
other See Repology for the full list

Windows

Manager Install Version
Scoop scoop install kubo
other See Repology for the full list

Chocolatey no longer supported (#9341)

Documentation

Topic Description
Configuration All config options reference
Environment variables Runtime settings via env vars
Experimental features Opt-in features in development
HTTP Gateway Path, subdomain, and trustless gateway setup
HTTP RPC clients Client libraries for Go, JS
Delegated routing Multi-router and HTTP routing
Metrics & monitoring Prometheus metrics
FUSE mounts Mount /ipfs, /ipns, /mfs as local filesystems
Content blocking Denylist for public nodes
Customizing Unsure if use Plugins, Boxo, or fork?
Debug guide CPU profiles, memory analysis, tracing
Changelogs Release notes for each version
All documentation Full list of docs

Development

See the Developer Guide for build instructions, testing, and contribution workflow. AI coding agents should follow AGENTS.md.

Getting Help

Security Issues

See SECURITY.md.

Contributing

We welcome contributions. See CONTRIBUTING.md and the Developer Guide.

This repository follows the IPFS Code of Conduct.

Maintainer Info

[!NOTE]
Kubo is maintained by the Shipyard team.

Release Process

License

Dual-licensed under Apache 2.0 and MIT:

File: assets/README.md

Assets loaded in with IPFS

This directory contains the go-ipfs assets:

  • Getting started documentation (init-doc).

File: client/rpc/README.md

`coreiface.CoreAPI` over http `rpc`

IPFS CoreAPI implementation using HTTP API

This package implements coreiface.CoreAPI over the HTTP API.

Documentation

https://pkg.go.dev/github.com/ipfs/kubo/client/rpc

Example

Pin file on your local IPFS node based on its CID:

go
package main

import (
	"context"
	"fmt"

	"github.com/ipfs/boxo/path"
	"github.com/ipfs/go-cid"
	"github.com/ipfs/kubo/client/rpc"
)

func main() {
	// "Connect" to local node
	node, err := rpc.NewLocalApi()
	if err != nil {
		fmt.Println(err)
		return
	}
	// Pin a given file by its CID
	ctx := context.Background()
	c, err := cid.Decode("bafkreidtuosuw37f5xmn65b3ksdiikajy7pwjjslzj2lxxz2vc4wdy3zku")
	if err != nil {
		fmt.Println(err)
		return
	}
	p := path.FromCid(c)
	err = node.Pin().Add(ctx, p)
	if err != nil {
		fmt.Println(err)
		return
	}
}

File: cmd/ipfswatch/README.md

IPFSWatch monitors a directory and adds changes to IPFS

text
ฮป. ipfswatch --help
  -path=".": the path to watch
  -repo="": IPFS_PATH to use

File: docs/changelogs/v0.2.md

go-ipfs changelog v0.2

0.2.3 - 2015-03-01

  • Alpha Release

2015-01-31:

  • bootstrap addresses now have .../ipfs/... in format
    config file Bootstrap field changed accordingly. users
    can upgrade cleanly with:

    text
    ipfs bootstrap >bootstrap_peers
ipfs bootstrap rm --all

<manually add .../ipfs/... to addrs in bootstrap_peers>
ipfs bootstrap add  (@whyrusleeping)
    • fix a few race conditions in mocknet (@whyrusleeping)
    • fix makefile failing when not in a git repo (@whyrusleeping)
    • fix cli flag orders (long, short) (@rht)
    • fix races in http cors (@miolini)
    • small webui update (some bugfixes) (@jbenet)

  • Tool Changes

    • make swarm connect return an error when it fails (@whyrusleeping)
    • Add short flag for ipfs ls --headers (v for verbose) (@rht)

  • General Codebase

    • bitswap: clean log printf and humanize dup data count (@cryptix)
    • config: update pluto's peerID (@lgierth)
    • config: update bootstrap list hostname (@lgierth)

  • Documentation

    • Pared down contribute to link to new go guidelines (@richardlitt)

  • Testing

    • t0010: add tests for 'ipfs commands --flags' (@chriscool)
    • ipns_test: fix namesys.NewNameSystem() call (@chriscool)
    • t0060: fail if no nc (@chriscool)

v0.3.8 - 2015-10-09

This patch update includes changes to make ipns more consistent and reliable,
symlink support in unixfs, mild performance improvements, new tooling features,
a plethora of bugfixes, and greatly improved tests.

NOTICE: Version 0.3.8 also requires golang version 1.5.1 or higher.

  • Bugfixes

    • refactor ipns to be more consistent and reliable (@whyrusleeping)
    • fix 'ipfs refs' json output (@whyrusleeping)
    • fix setting null config maps (@rht)
    • fix output of dht commands (@whyrusleeping)
    • fix NAT spam dialing (@whyrusleeping)
    • fix random panics on 32 bit systems (@whyrusleeping)
    • limit total number of network fd's (@whyrusleeping)
    • fix http api content type (@WeMeetAgain)
    • fix writing of api file for port zero daemons (@whyrusleeping)
    • windows connection refused fixes (@mjanczyk)
    • use go1.5's built in trailers, no more failures (@whyrusleeping)
    • fix random bitswap hangs (@whyrusleeping)
    • rate limit fd usage (@whyrusleeping)
    • fix panic in bitswap rate limiting (@whyrusleeping)

  • Tool Changes

    • --empty-repo option for init (@prusnak)
    • implement symlinks (@whyrusleeping)
    • improve cmds lib files processing (@rht)
    • properly return errors through commands (@whyrusleeping)
    • bitswap unwant command (@whyrusleeping)
    • tar add/cat commands (@whyrusleeping)
    • fix gzip compression in get (@klauspost)
    • bitswap stat logs wasted bytes (@whyrusleeping)
    • resolve command now uses core.Resolve (@rht)
    • add --local flag to 'name resolve' (@whyrusleeping)
    • add ipfs diag sys command for debugging help (@whyrusleeping)

  • General Codebase

    • improvements to dag editor (@whyrusleeping)
    • swarm IPv6 in default config (Baptiste Jonglez)
    • improve dir listing css (@rht)
    • removed elliptic.P224 usage (@prusnak)
    • improve bitswap providing speed (@jbenet)
    • print panics that occur in cmds lib (@whyrusleeping)
    • ipfs api check test fixes (@rht)
    • update peerstream and datastore (@whyrusleeping)
    • cleaned up tar-reader code (@jbenet)
    • write context into coreunix.Cat (@rht)
    • move assets to separate repo (@rht)
    • fix proc/ctx wiring in bitswap (@jbenet)
    • rabin fingerprinting chunker (@whyrusleeping)
    • better notification on daemon ready (@rht)
    • coreunix cat cleanup (@rht)
    • extract logging into go-log (@whyrusleeping)
    • blockservice.New no longer errors (@whyrusleeping)
    • refactor ipfs get (@rht)
    • readonly api on gateway (@rht)
    • cleanup context usage all over (@rht)
    • add xml decoding to 'object put' (@ForrestWeston)
    • replace nodebuilder with NewNode method (@whyrusleeping)
    • add metrics to http handlers (@lgierth)
    • rm blockservice workers (@whyrusleeping)
    • decompose maybeGzWriter (@rht)
    • makefile sets git commit sha on build (@CaioAlonso)

  • Documentation

    • add contribute file (@RichardLitt)
    • add go devel guide to contribute.md (@whyrusleeping)

  • Testing

    • fix mock notifs test (@whyrusleeping)
    • test utf8 with object cmd (@chriscool)
    • make mocknet conn close idempotent (@jbenet)
    • fix fuse tests (@pnelson)
    • improve sharness test quoting (@chriscool)
    • sharness tests for chunker and add-cat (@rht)
    • generalize peerid check in sharness (@chriscool)
    • test_cmp argument cleanup (@chriscool)

v0.3.7 - 2015-08-02

This patch update fixes a problem we introduced in 0.3.6 and did not
catch: the webui failed to work with out-of-the-box CORS configs.
This has been fixed and now should work correctly. @jbenet

v0.3.6 - 2015-07-30

This patch improves the resource consumption of go-ipfs,
introduces a few new options on the CLI, and also
fixes (yet again) windows builds.

  • Resource consumption:

    • fixed goprocess memory leak @rht
    • implement batching on datastore @whyrusleeping
    • Fix bitswap memory leak @whyrusleeping
    • let bitswap ignore temporary write errors @whyrusleeping
    • remove logging to disk in favor of api endpoint @whyrusleeping
    • --only-hash option for add to skip writing to disk @whyrusleeping

  • Tool changes

    • improved ipfs daemon output with all addresses @jbenet
    • improved ipfs id -f output, added <addrs> and \n \t support @jbenet
    • ipfs swarm addrs local now shows the local node's addrs @jbenet
    • improved config json parsing @rht
    • improved Dockerfile to use alpine linux @Luzifer @lgierth
    • improved bash completion @MichaelMure
    • Improved 404 for gateway @cryptix
    • add unixfs ls to list correct filesizes @wking
    • ignore hidden files by default @gatesvp
    • global --timeout flag @whyrusleeping
    • fix random API failures by closing resp bodies @whyrusleeping
    • ipfs swarm filters @whyrusleeping
    • api returns errors in http trailers @whyrusleeping @jbenet
    • ipfs patch learned to create intermediate nodes @whyrusleeping
    • ipfs object stat now shows Hash @whyrusleeping
    • ipfs cat now clears progressbar on exit @rht
    • ipfs add -w -r <dir> now wraps directories @jbenet
    • ipfs add -w <file1> <file2> now wraps with one dir @jbenet
    • API + Gateway now support arbitrary HTTP Headers from config @jbenet
    • API now supports CORS properly from config @jbenet
    • Deprecated: API_ORIGIN env var (use config, see ipfs daemon --help) @jbenet

  • General Codebase

    • nofuse tag for windows @Luzifer
    • improved ipfs add code @gatesvp
    • started requiring license trailers @chriscool @jbenet
    • removed CtxCloser for goprocess @rht
    • remove deadcode @lgierth @whyrusleeping
    • reduced number of logging libs to 2 (soon to be 1) @rht
    • dial address filtering @whyrusleeping
    • Prometheus metrics @lgierth
    • new index page for gateway @krl @cryptix
    • move ping to separate protocol @whyrusleeping
    • add events to bitswap for a dashboard @whyrusleeping
    • add latency and bandwidth options to mocknet @heems
    • levenshtein distance cmd autosuggest @sbruce
    • refactor/cleanup of cmds http handler @whyrusleeping
    • cmds http stream reports errors in trailers @whyrusleeping

  • Bugfixes

    • fixed path resolution and validation @rht
    • fixed ipfs get -C output and progress bar @rht
    • Fixed install pkg dist bug @jbenet @Luzifer
    • Fix ipfs get silent failure @whyrusleeping
    • ipfs get tarx no longer times out @jbenet
    • ipfs refs -r -u is now correct @gatesvp
    • Fix ipfs add -w -r <dir> wrapping bugs @jbenet
    • Fixed FUSE unmount failures @jbenet
    • Fixed ipfs log tail command (api + cli) @whyrusleeping

  • Testing

    • sharness updates @chriscool
    • ability to disable secio for testing @jbenet
    • fixed many random test failures, more reliable CI @whyrusleeping
    • Fixed racey notifier failures @whyrusleeping
    • ipfs refs -r -u test cases @jbenet
    • Fix failing pinning test @jbenet
    • Better CORS + Referer tests @jbenet
    • Added reversible gc test @rht
    • Fixed bugs in FUSE IPNS tests @whyrusleeping
    • Fixed bugs in FUSE IPFS tests @jbenet
    • Added random-files tool for easier sharness tests @jbenet

  • Documentation

    • Add link to init system examples @slang800
    • Add CORS documentation to daemon init @carver (Note: this will change soon)

v0.3.5 - 2015-06-11

This patch improves overall stability and performance

  • added 'object patch' and 'object new' commands @whyrusleeping
  • improved symmetric NAT avoidance @jbenet
  • move util.Key to blocks.Key @whyrusleeping
  • fix memory leak in provider store @whyrusleeping
  • updated webui to 0.2.0 @krl
  • improved bitswap performance @whyrusleeping
  • update fuse lib @cryptix
  • fix path resolution @wking
  • implement test_seq() in sharness @chriscool
  • improve parsing of stdin for commands @chriscool
  • fix 'ipfs refs' failing silently @whyrusleeping
  • fix serial dialing bug @jbenet
  • improved testing @chriscool @rht @jbenet
  • fixed domain resolving @luzifer
  • fix parsing of unwanted stdin @lgierth
  • added CORS handlers to gateway @NodeGuy
  • added ipfs daemon --unrestricted-api option @krl
  • general cleanup of dependencies

v0.3.4 - 2015-05-10

  • fix ipns append bug @whyrusleeping
  • fix out of memory panic @whyrusleeping
  • add in expvar metrics @tv42
  • bitswap improvements @whyrusleeping
  • fix write-cache in blockstore @tv42
  • vendoring cleanup @cryptix
  • added launchctl plist for OSX @grncdr
  • improved Dockerfile, changed root and mount paths @ehd
  • improved pin ls output to show types @vitorbaptista

v0.3.3 - 2015-04-28

This patch update fixes various issues, in particular:

  • windows support (0.3.0 had broken it)
  • command line parses spaces correctly.
  • much improved command line parsing by @AtnNn
  • improved dockerfile by @luzifer
  • add cmd cleanup by @wking
  • fix flatfs windows support by @tv42 and @gatesvp
  • test case improvements by @chriscool
  • ipns resolution timeout bug fix by @whyrusleeping
  • new cluster tests with iptb by @whyrusleeping
  • fix log callstack printing bug by @whyrusleeping
  • document bash completion by @dylanPowers

v0.3.2 - 2015-04-22

This patch update implements multicast dns as well as fixing a few test issues.

  • implement mdns peer discovery @whyrusleeping
  • fix mounting issues in sharness tests @chriscool

v0.3.1 - 2015-04-21

This patch update fixes a few bugs:

  • harden shutdown logic by @torarnv
  • daemon locking fixes by @travisperson
  • don't re-add entire dirs by @whyrusleeping
  • tests now wait for graceful shutdown by @jbenet
  • default key size is now 2048 by @jbenet

v0.3.0 - 2015-04-20

We've just released version 0.3.0, which contains many
performance improvements, bugfixes, and new features.
Perhaps the most noticeable change is moving block storage
from leveldb to flat files in the filesystem.

What to expect:

  • much faster performance

  • Repo format 2

    • moved default location from ~/.go-ipfs -> ~/.ipfs
    • renamed lock filename daemon.lock -> repo.lock
    • now using a flat-file datastore for local blocks

  • Fixed lots of bugs

    • proper ipfs-path in various commands
    • fixed two pinning bugs (recursive pins)
    • increased yamux streams window (for speed)
    • increased bitswap workers (+ env var)
    • fixed memory leaks
    • ipfs add error returns
    • daemon exit bugfix
    • set proper UID and GID on fuse mounts

  • Gateway

    • Added support for HEAD requests

  • configuration

    • env var to turn off SO_REUSEPORT: IPFS_REUSEPORT=false
    • env var to increase bitswap workers: IPFS_BITSWAP_TASK_WORKERS=n

  • other

    • bash completion is now available
    • ipfs stats bw -- bandwidth metering

And many more things.

2. Official Technical Reference & Guides (ipfs/ipfs-docs)

File: README.md

Welcome to the official IPFS documentation. The Interplanetary File System (IPFS) is a distributed, peer-to-peer network for storing and accessing files, websites, applications, and data. Protocol Labs is the primary maintainer of the IPFS documentation and will review all issues and pull requests created in this repository.

If you'd just like to read the IPFS documentation, we recommend the website version.

Project set up

Run locally

To build the site locally, follow the steps below.

  1. Clone this repository:

    bash
    git clone https://github.com/ipfs/ipfs-docs.git

  2. Move into the ipfs-docs folder:

    bash
    cd ipfs-docs

  3. Install the NPM dependencies:

    bash
    npm install

  4. Boot up the application in dev mode:

    bash
    npm start

  5. Open http://localhost:8080 in your browser.

  6. Close the local server with CTRL + c.

  7. To restart the local server, run npm start from within the ipfs-docs folder.

Troubleshooting

If you're having trouble setting up the site locally, check this section for solutions to common issues.

Digital envelope routines initialization error

The following error message may display when using Node.js version 18.0.0 when attempting to deploy this project for the first time:

shell
opensslErrorStack: [ 'error:03000086:digital envelope routines::initialization error' ],
library: 'digital envelope routines',
reason: 'unsupported',
code: 'ERR_OSSL_EVP_UNSUPPORTED'

To solve this error, perform the following steps:

  1. Open a terminal.

  2. Navigate into the ipfs-docs folder:

    bash
    cd ipfs-docs

  3. Run the following command:

    shell
    export NODE_OPTIONS=--openssl-legacy-provider

  4. Run npm start.

    bash
    npm start

You can return to the Project set-up section above and continue with the steps. You can also check this issue in the Webpack GitHub repository for more information about this error.

Contribute to documentation

We would love โค๏ธ your help to improve existing items or make new ones even better! See the IPFS Bounties page!

Issues

If you find something wrong within this repository, please raise an issue here โ†’. Unless the issue is urgent, updates will be batch-merged into main on Tuesdays or Thursdays.

Bounties

You can earn the undying love of the IPFS community, and get rewarded by closing an issue containing the bounty tag. Submissions must be production-ready and meet all the specifications listed on the issue page. To get started, check out IPFS Bounties.

If you are attempting to close an issue, great! Thanks for the help! Please leave a comment within the issue requesting to be assigned to that issue before submitting a pull request. This minimizes the chance of multiple contributors duplicating work by submitting pull requests for the same issue. If you submit a pull request to an issue without first being assigned to it, your pull request may not be accepted.

Suggestions

Everyone has an opinion when it comes to documentation, and that's a good thing! Having folks from different backgrounds add to a discussion empowers everyone within that discussion, so if you've got something to add or would like to bring up a topic for discussion about the documentation, please do so! Create an issue using the kind/question tag.

Pull requests welcome

Feel free to submit pull requests with any changes you'd like to see. We will review and approve, or leave change requests, as soon as we are able.

Style and configuration guide

A writing style and template guide is in the process of being written that contributors can use as a guideline.

Static-site generator

The IPFS documentation site uses the VuePress static website generator to convert the Markdown guides into a documentation website. All the documentation is written in Markdown; follow the VuePress Markdown documentation for information on how to write markdown files for VuePress.

Automated deployments

When opening a pull request, CI scripts will run against your feature branch to test your changes.

The CI/CD production workflow builds on the main branch and deploys the documentation site via GitHub Pages for HTTPS hosting. PR and IPFS (CAR) previews are provided by ipfs-deploy-action. The site reflects the latest commit on main.

License

All software code is copyright (c) Protocol Labs, Inc. under the MIT license. Other written documentation and content are copyright (c) Protocol Labs, Inc. under the Creative Commons Attribution-Share-Alike License.

File: docs/quickstart/retrieve.md

title: 'Retrieval with IPFS'

Retrieving a CID with IPFS

In this quickstart guide, you will learn the different approaches to retrieving CIDs from the IPFS network and how to pick the most appropriate method for your specific needs.

You will fetch the image with the following CID: bafkreie7ohywtosou76tasm7j63yigtzxe7d5zqus4zu3j6oltvgtibeom.

:::callout
The CID you will retrieve is actually a folder containing a single image file. The reason for this that when files are added to IPFS, the filename is not stored by default. To retain the filename, it's a common practice to wrap the file in a directory. In such instances, you end up with two CIDs - one for the file and another for the directory containing the file.
:::

Contents

IPFS retrieval methods

There are two primary ways to retrieve files and directories published to IPFS:

  • Use an IPFS node by installing one of the IPFS implementations, e.g. Kubo on your computer. This allows you to fetch and verify CIDs from other nodes in the IPFS network.
  • Use an IPFS Gateway, an HTTP interface with the IPFS network that allows you to fetch data from IPFS using HTTP. Pinning services typically offer an IPFS gateway as a way to easily retrieve your CIDs.

The node option allows you access to the full suite of IPFS protocols. The Gateway option serves as a bridge in situations where you might be constrained to using HTTP, such as in web apps where your app users may not be running an IPFS node.

IPFS Gateways, in their most basic form, are typically IPFS nodes that are hosted by someone else and expose an HTTP interface to fetch CIDs, as shown in the diagram below:

Verified vs. trusted CID retrieval

Another thing to consider when deciding between the two approaches is verification. By default, an IPFS node hashes each block and ensures that, when the file is constructed from the blocks (into a Merkle DAG), it results in the CID you requested. However, with IPFS Gateways, verification is optional.

Non-verified retrieval is also commonly referred to as trusted retrieval because you're trusting the gateway to return the correct response without calculating the hash.

While verification is almost always recommended, in reality, there are situations where trusted retrieval is the pragmatic choice, such as when embedding images on a website.

Fetching the CID with Kubo

To fetch the CID with Kubo, complete the steps below:

  1. Ensure that the Kubo daemon is installed and running:

    bash
    $ ipfs daemon

  2. To fetch the file, run the ipfs get [CID] command:

    bash
    $ ipfs get bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4

    The output should look as follows:

    bash
    Saving file(s) to bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4
647.61 KiB / 647.61 KiB [========================================================================================================================] 100.00% 0s

    A new folder with the same name as the CID was created:

    bash
    $ ls bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4/
welcome-to-IPFS.jpg

Congratulations, you have successfully fetched the CID.

Verified retrieval with Helia Verified Fetch

Verified Fetch simplifies verified retrieval of CIDs on the web by abstracting away the details of content routing, transports and retrieval. The API is similar to the Fetch API, accepting CIDs instead of URLs, returning Response objects.

For example, the following code fetches the image using the verifiedFetch library:

See the Pen
Fetch an image on IPFS Mainnet @helia/verified-fetch by Daniel Norman (@2color)
on CodePen.

:::callout
You may notice that there's a path following the CID, e.g. bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4/welcome-to-IPFS.jpg, because the starting CID is a directory containing the welcome-to-IPFS.jpg file, which you can fetch directly with: verifiedFetch('ipfs://bafkreie7ohywtosou76tasm7j63yigtzxe7d5zqus4zu3j6oltvgtibeom').
:::

Fetching the CID with Python and ipfsspec

ipfsspec is a read-only fsspec implementation for IPFS. It performs verified HTTP retrieval from gateways by fetching CAR files containing Merkle proofs, so you don't have to trust the gateway. It works without a local IPFS node.

  1. Install fsspec and ipfsspec:

    bash
    pip install fsspec ipfsspec

  2. Fetch the image using fsspec.open:

python
import fsspec

cid = "ipfs://bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4/welcome-to-IPFS.jpg"

with fsspec.open(cid, "rb") as f:
    image_data = f.read()
    print(f"Retrieved {len(image_data)} bytes")

You can also address the file directly by its own CID:

python
with fsspec.open("ipfs://bafkreie7ohywtosou76tasm7j63yigtzxe7d5zqus4zu3j6oltvgtibeom", "rb") as f:
    image_data = f.read()

To determine which gateway to use, ipfsspec follows IPIP-280. You can point it at a different gateway, via the options, by setting the IPFS_GATEWAY environment variable or writing the gateway URL to ~/.ipfs/gateway.

Fetching the CID with an IPFS Gateway

To fetch the CID using an IPFS gateway is as simple as loading one of the following URLs:

inbrowser.link is powered by the Service Worker Gateway which handles retrieval and verification in the browser, also leveraging in-browser caching, making subsequent loads faster, and local when you're offline.

Summary and next steps

In this quickstart guide, you learned the different approaches to retrieving CIDs from the IPFS network and how to pick the most appropriate method for your specific needs.

You then fetched the image that was pinned in the publishing with a pinning service quickstart guide using an IPFS Kubo node and an IPFS Gateway.

Possible next steps include:

File: docs/project/history.md

title: History related: 'Video: Juan Benet explains the IPFS alpha': https://www.youtube.com/watch?v=skMTdSEaCtA 'IPFS draft whitepaper': https://ipfs.io/ipfs/QmR7GSQM93Cx5eAg6a6yRzNde1FQv7uL6X1o4k7zrJa3LX/ipfs.draft3.pdf 'Video: Decentralizing the Web with the InterPlanetary File System (Epicenter Podcast)': https://www.youtube.com/watch?v=erB7i6Uc4DM "Article: It's time for the distributed web โ€” September 2015 (Neocities)": https://blog.neocities.org/blog/2015/09/08/its-time-for-the-distributed-web.html

History of the IPFS project

Like Westeros, peer-to-peer (P2P) technology has experienced years-long winters and summers. There have been periods of great excitement and growth. Other times, P2P innovation has gone into hibernation.

Tim Berners-Lee first envisioned the World Wide Web with P2P concepts. The emergent properties of the web did not evolve true to that vision. Centralized, client-server architectures dominate todayโ€™s web.

The InterPlanetary File System (IPFS) Project aims to return the web to its P2P roots: making the web faster, safer, and more open.

A P2P summer (1999~2003)

In 1999, Napster took the world by storm by offering unlimited, free music. Record labels hadn't pivoted to a new business model (yet). Users were sharing media files freely because Napster's peer-to-peer network removed the barriers to doing so.

What followed was a period of great innovation in P2P technology. Exciting ideas and companies sprouted: Gnutella, Kazaa, MojoNation, BitTorrent, Skype, and many more.

Some of these projects appealed to technologists on ideological grounds. The projects that won mass markets did so on their merits. Like Napster, Skype and BitTorrent broke through because their P2P architectures enabled novel, valuable services.

This era ended partially under the weight of legal scrutiny. A significant amount of sharing on these P2P systems was of copyrighted material. The resulting stigma suppressed P2P innovation, but competitive forces also played a role.

Client-server architectures lend themselves to centralized control and monetization. Centralized services aggregated more and more value on the web. Profits drove a flywheel of investment and hyper-scale growth for years to come.

This P2P summer proved that projects could win because of their P2P architectures, not in spite of them. These projects demonstrated the possible. With time and technological progress, P2P would return to make an even bigger impact.

IPFS origins and a new P2P summer (2013 - 2017)

Juan Benet grew up in this previous P2P summer. He experienced the power of P2P networks firsthand. When he studied computer science at Stanford, he took special interest in distributed networks.

In 2013, Juan was working on a project aimed at another passionโ€“scientific innovation. Inspiration struck. The tools used for sharing and versioning large datasets were inefficient and error-prone. Worse, this type of human knowledge was too often centralized behind a paywall. With his background in software development and P2P systems, he knew there was a better way.

Git manages software versioning and collaboration through a data-linking structure known as a Merkle tree. Git's data-linking structure is useful across many data types โ€“ not just code. Juan recognized that combining this concept with the P2P file-sharing structure of BitTorrent would be powerful: functional, secure information sharing without centralized barriers. This could transform the world far beyond scientific datasets.

The IPFS project was born.

As ambitious as IPFS was, Juan's vision didn't stop there. He founded Protocol Labs in May 2014 to support fundamental research, development, and deployment of infrastructure for open networks (like the internet), with IPFS and its complementary incentivization layer, Filecoin, as the first projects. Protocol Labs was modeled to be like an independent Bell Labs (outside of the IPFS ecosystem, Protocol Labs has since spawned projects including Coinlist, The SAFT Project, and SourceCred).

Protocol Labs entered the Y Combinator Summer 2014 Class. Juan got to work writing code and the IPFS whitepaper.

The whitepaper was published in July 2014. It caught the attention of P2P and internet enthusiasts, including Jeromy Johnson (aka whyrusleeping). "Why" and other early contributors shared Juan's vision for a distributed, uncensorable, and permissionless file system. They worked nights and weekends, and initially for free, because they believed in the positive impact that open networks like IPFS could have on the world.

Juan, Why, and other contributors spent many late nights in Juan's living room with takeout food and too many coffees (Philz Mint Mojitos FTW!) to create the alpha release of Kubo. IPFS was ready to begin its growth journey in the open.

In the summer of 2015, the small but growing IPFS team (about five or six full-time contributors) settled into a coworking space in Seattle. They hammered out improvements to the Go and JavaScript implementations of IPFS as interest in the project grew. Satoshi Nakamoto's 2009 Bitcoin whitepaper had ushered in a renaissance of P2P innovation. A P2P summer was in full swing. IPFS gained usage in the Ethereum and wider blockchain communities. In September 2015, Neocities became the first major site to implement IPFS in production.

The work done in Seattle and the lessons learned working with Neocities culminated in the 0.4.0 release of Kubo in April 2016. The improvements of 0.4.0 transitioned IPFS from an "exciting demo" to a genuinely useful tool for early adopters.

The project saw further technical and community growth in 2016. Multiformats, libp2p, and IPLD were spun out as separate projects from IPFS. The IPFS team attended and hosted many community gatherings highlighted by the Decentralized Web Summit.

Two watershed moments in 2017 validated the growing excitement around IPFS. The first was jumpstarted by a passionate individual with an idea โ€” fittingly enough for a P2P technology like IPFS. Jakub Sztandera (aka Kubuxu), an IPFS software engineer, took it upon himself to download the Turkish version of Wikipedia and put the snapshot onto IPFS in response to state censorship. This undertaking exemplified the project's values. An energized team and community rallied to deliver new performance upgrades to IPFS. The second major event was Protocol Labs' $205.8M Filecoin Token Sale. With significant funding and a reinforced sense of purpose, Protocol Labs' and IPFS' ambitious founding visions were in reach, but not yet realized.

The next chapter (2018 - today)

According to Uncle Ben, with great power comes great responsibility. So in 2018, IPFS entered the next phase of its maturation. The project needed to deliver on its ideological and technical advantages at scale. As seen in previous P2P eras, theoretical advantages must translate to tangible developer and user benefits in order to win over the mass market. With a growing team, multiple interdependent projects, and an ecosystem of users and partners, the team began developing, sharing, and executing product roadmaps to maturity.

This focus bore significant results in the IPFS community in 2019. Protocol Labs hosted the first IPFS Camp in Barcelona in June. The retreat brought together 150 distributed-web pioneers to learn, collaborate, and build. It inspired a successful collaboration with one of the biggest, most innovative corporations in world, Netflix. By the end of 2019, the IPFS network had grown by more than 30x. The community of open-source contributors stood at more than 4,000.

The April 2020 Kubo 0.5.0 release provided the largest performance upgrades to the network yet: faster file adding (2x), providing (2.5x), finding (2-6x), and fetching (2-5x). For the ever-growing IPFS ecosystem, reliability is just as important as speed. For that, Protocol Labs developed, used, and released Testground. Testground is a huge step forward in testing and hardening P2P systems not just for IPFS, but the community at-large.

Major collaborations with Opera, Microsoft ION, and Cloudflare just scratch the surface of possibilities for IPFS. The H2 2020 Filecoin Mainnet launch is poised to fundamentally shift economic incentives of the P2P IPFS network to compete with the entrenched client-server web.

IPFS has come a long way in the journey to building a faster, safer, and more open web to preserve and grow humanity's knowledge. The beautiful thing is, that journey is never ending. This is still just the beginning!

File: docs/project/README.md

title: Project

The IPFS project

Looking to get further involved with the vibrant IPFS community and ecosystem? Curious about how it all got started, or where we're headed? Learn how to get involved, the project history, and more.

IPFS community and ecosystem

:::callout
The IPFS community believes that our mission is best served in an environment that is friendly, safe, and accepting, and free from intimidation or harassment. To that end, we ask that everyone involved in IPFS read and respect our code of conduct. Please contact [email protected] if you need to report a problem or address a grievance related to an abuse report. For reporting abuse at public utilities such as gateways, see the abuse policy.
:::

The community and ecosystem around the IPFS project is large, diverse, and abounds with opportunities for involvement. Learn more in the Community section.

History of IPFS

Want to know how it all began? Learn the history of the IPFS project.

Repository guide

IPFS is a big project, which means there are a lot of GitHub repos. If you're new to IPFS or just want a sense of what to check out first, use this quick guide to the most important and most frequently used IPFS repositories.

IPFS specifications

Technical specifications for the IPFS protocol and its associated subsystems.

Research

Learn more about the exploratory research work and prototyping being done for inclusion in IPFS by exploring our research repo on GitHub.

IPFS is a highly modular project that is itself made out of many different protocols and tools. Learn more about the IPFS-related projects under the overall support of Protocol Labs.

Contribute to IPFS

Thousands of people contribute to IPFS from all over the world โ€” and that can include you! No matter your areas of interest or expertise, there are a number of ways that you can make an impact on the future of the Internet by contributing to IPFS.

IPFS is a highly modular project that is itself made out of many different protocols and tools. Many of these exist as their own projects under the overall support of Protocol Labs. Learn more about them below.

IPLD

IPLD is the data model of the content-addressable web. It allows us to treat all hash-linked data structures as subsets of a unified information space, unifying all data models that link data with hashes as instances of IPLD. Learn more at https://ipld.io/.

libp2p

A modular network stack, libp2p enables you to run your network applications free from runtime and address services, independently of their location. Learn more at http://libp2p.io/.

IPFS Cluster

IPFS Cluster provides data orchestration across a swarm of IPFS daemons by allocating, replicating and tracking a global pinset distributed among multiple peers. Learn more at https://ipfscluster.io/.

DNSLink is a very simple protocol to link content and services directly from DNS, leveraging the powerful distributed architecture of DNS for a variety of systems that require internet-scale mutable names or pointers. Learn more at http://dnslink.io/.

Multiformats

The Multiformats Project is a collection of protocols which aim to future-proof systems through self-describing format values that allow for interoperability and protocol agility. Learn more at https://multiformats.io/.

ProtoSchool

Interactive tutorials on decentralized web protocols, with code challenges you complete in your web browser. The project is archived: https://proto.school/ is still online, but the last tutorial landed in February 2021 and the code challenges use js-ipfs, which Helia replaced in 2023.

File: docs/project/repository-guide.md

title: Repository guide

IPFS repository guide

IPFS is an extensive open-source project, and with that comes a lot of code and issue-based discussions. The IPFS project uses GitHub for both code development and road mapping and operations discussions, meaning that both types of activities can happen asynchronously, in the open, and from anywhere on the planet.

If you're looking for specific IPFS-related code, or want to find where to join in a particular discussion, start with this high-level guide to the most prominent and/or frequently used GitHub organizations and repositories in the IPFS project. It's not an exhaustive list of all IPFS organizations and repositories, but instead is intended to help guide you based on what you are trying to do in the following areas:

Fetch or contribute to IPFS code

Organization and repository links for the top-level projects shipped as part of the IPFS project and the main repos for each ingredient in the stack upon which IPFS is built.

Protocol implementations

:::warning

js-ipfs was discontinued

The js-ipfs project was archived in 2023 in favor of Helia, a leaner, more modular, modern implementation of IPFS in JavaScript. See the deprecation announcement for the migration path.

Any js-ipfs tutorial you find is out of date. Use Helia instead.

:::

  • Kubo: The reference implementation written in Go.
  • Helia: The JavaScript and TypeScript implementation of IPFS.
  • rust-ipfs: Implementation in Rust.
  • Other implementations: Up-to-date links to all other protocol implementations.

Client implementations

Underlying components

Subsystem Go JavaScript Rust
LibP2P go-libp2p js-libp2p rust-libp2p
IPLD go-ipld , go-ipld-prime js-ipld libipld
IPNS go-ipns js-ipns rust-ipns
Multiaddr go-multiaddr js-multiaddr rust-multiaddr
Multicodec go-multicodec js-multiformats N/A
Multihash go-multihash js-multiformats rust-multihash
Multibase go-multibase js-multiformats rust-multibase
CID N/A js-multiformats rust-cid

IPFS tools and products

  • IPFS Cluster: Automatically allocate, replicate, and track your data as a global pinset distributed among a swarm of peers.
  • IPFS Companion: The IPFS web browser extension.
  • IPFS Web UI: An easy-to-use web interface for IPFS nodes.
  • IPFS Desktop: Standalone IPFS app with an easy-to-use node interface, plus menubar/tray shortcuts
  • ipfs-gui: Coordinating development, user experience, and maintenance of IPFS GUIs.
  • IPFS Shipyard: GitHub org showcasing incubated projects of all types created by the global IPFS community.

Interoperability, platforms, and standards

Participate in IPFS project operations

IPFS project operations at large are also captured in GitHub. These repos don't necessarily contain code but do follow a similar pattern of issue creation, discussion, and resolution via comments and linked artifacts.

Operations discussions and tools

Internationalization

  • i18n: The IPFS Translation Project, crowdsourcing translations of IPFS GUIs and websites.

File: docs/install/command-line.md

title: Kubo current-ipfs-version: v0.43.0

Install IPFS Kubo

This guide describes the available installation processes for IPFS Kubo, a Go-based implementation of the InterPlanetary File System (IPFS) protocol. Kubo was the first implementation of IPFS, and is the most widely used implementation today. Kubo allows you to do everything that IPFS Desktop can do, but at a more granular level, since you can specify which commands to run. Kubo has the following features:

Installing Kubo in the command line is handy for many use cases, such as building applications and services on top of an IPFS node, or setting up a node without a user interface (which is usually the case with remote servers or virtual machines).

To get started, familiarize yourself with the system requirements. Then, determine if you'd like to install Kubo using one of the 5 official binary distributions, or build Kubo from source. Once you've installed Kubo, determine which node to use in the command line. Finally, check out the next steps.

:::warning
Building from source is only recommended if you are running Kubo on a system with severe resource constraints, or are contributing to the Kubo project.
:::

System requirements

Kubo runs on most Windows, MacOS, Linux, FreeBSD and OpenBSD systems that meet the following requirements:

  • 6 GiB of memory.
  • 2 CPU cores (kubo is highly parallel).

Note the following:

  • The amount of disk space your IPFS installation uses depends on how much data you're sharing. A base installation uses around 12MB of disk space.
  • You can enable automatic garbage collection via --enable-gc and adjust using default maximum disk storage for data retrieved from other peers.

Install official binary distributions

This section describes how to download and install the Kubo binary from dist.ipfs.tech on Windows, MacOS, Linux, FreeBSD and OpenBSD operating systems. The IPFS team publishes the latest, official prebuilt Kubo binaries on the dist.ipfs.tech website. New IPFS Kubo binary releases are automatically shown on the Kubo page on dist.ipfs.tech.

:::callout
If you are unable to access dist.ipfs.tech, you can also download Kubo from the project's GitHub releases page or /ipns/dist.ipfs.tech at the dweb.link gateway.
:::

For installation instructions for your operating system, select the appropriate tab.

:::: tabs

::: tab Linux id="install-kubo-linux"

Linux

  1. Download the Linux binary from dist.ipfs.tech.

    bash
    wget https://dist.ipfs.tech/kubo/v0.43.0/kubo_v0.43.0_linux-amd64.tar.gz

  2. Unzip the file:

    bash
    tar -xvzf kubo_v0.43.0_linux-amd64.tar.gz

> x kubo/install.sh
> x kubo/ipfs
> x kubo/LICENSE
> x kubo/LICENSE-APACHE
> x kubo/LICENSE-MIT
> x kubo/README.md

  3. Move into the kubo folder:

    bash
    cd kubo

  4. Run the installation script

    bash
    sudo bash install.sh

> Moved ./ipfs to /usr/local/bin

  5. Test that Kubo has installed correctly:

    bash
    ipfs --version

> ipfs version 0.43.0

:::

::: tab Windows id="install-kubo-windows"

Windows

  1. Download the Windows binary from dist.ipfs.tech.

    powershell
    wget https://dist.ipfs.tech/kubo/v0.43.0/kubo_v0.43.0_windows-amd64.zip -Outfile kubo_v0.43.0.zip

  2. Unzip the file to a sensible location, such as ~\Apps\kubo_v0.43.0.

    powershell
    Expand-Archive -Path kubo_v0.43.0.zip -DestinationPath ~\Apps\kubo_v0.43.0

  3. Move into the kubo_v0.43.0 folder

    powershell
    cd ~\Apps\kubo_v0.43.0\kubo

  4. Check that the ipfs.exe works:

    powershell
    .\ipfs.exe --version

> ipfs version 0.43.0

    At this point, Kubo is usable. However, it's strongly recommended that you first add ipfs.exe to your PATH using the following steps:

  5. Save the current working directory into a temporary variable:

    powershell
    $GO_IPFS_LOCATION = pwd

  6. Create a PowerShell profile:

    powershell
    if (!(Test-Path -Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force }

    This command first checks to see if you have a profile set. If you do, it leaves it there and doesn't create a new one. You can view the contents of your profile by opening it in an editor, such as Notepad:

    powershell
    notepad $PROFILE

  7. Add the location of your Kubo daemon and add it to PowerShell's PATH by truncating it to the end of your PowerShell profile:

    powershell
    Add-Content $PROFILE "`n[System.Environment]::SetEnvironmentVariable('PATH',`$Env:PATH+';;$GO_IPFS_LOCATION')"

  8. Load your $PROFILE:

    powershell
    & $profile

  9. Navigate to your home folder

    powershell
    cd ~

  10. Test that Kubo installed correctly:

    powershell
    ipfs --version

> ipfs version 0.43.0

:::

::: tab macOS id="install-kubo-mac"

macOS

The brew installation method supports both Intel and Apple Silicon hardware. If you prefer a manual installation, darwin-amd64 (Intel) and darwin-arm64 (Apple Silicon) artifacts available here.

  1. Navigate to a terminal.

  2. Use brew to install Kubo:

    shell
    brew install ipfs

  3. Confirm your Kubo installation:

    bash
    ipfs --version

    If Kubo is installed, the version number displays. For example:

    bash
    > ipfs version 0.43.0

:::

::: tab FreeBSD id="install-kubo-freeBSD"

FreeBSD

  1. Download the FreeBSD binary from dist.ipfs.tech.

    bash
    wget https://dist.ipfs.tech/kubo/v0.43.0/kubo_v0.43.0_freebsd-amd64.tar.gz

  2. Unzip the file:

    bash
    tar -xvzf kubo_v0.43.0_freebsd-amd64.tar.gz

> x kubo/install.sh
> x kubo/ipfs
> x kubo/LICENSE
> x kubo/LICENSE-APACHE
> x kubo/LICENSE-MIT
> x kubo/README.md

  3. Move into the kubo folder:

    bash
    cd kubo

  4. Run the install script:

    bash
    doas bash install.sh

> Moved ./ipfs to /usr/local/bin

  5. Test that Kubo has installed correctly:

    bash
    ipfs --version

> ipfs version 0.43.0

:::

::: tab OpenBSD id="install-kubo-openBSD"

OpenBSD

  1. Download the OpenBSD binary from dist.ipfs.tech.

    bash
    wget https://dist.ipfs.tech/kubo/v0.43.0/kubo_v0.43.0_openbsd-amd64.tar.gz

  2. Unzip the file:

    bash
    tar -xvzf kubo_v0.43.0_openbsd-amd64.tar.gz

> x kubo/install.sh
> x kubo/ipfs
> x kubo/LICENSE
> x kubo/LICENSE-APACHE
> x kubo/LICENSE-MIT
> x kubo/README.md

  3. Move into the kubo folder:

    bash
    cd kubo

  4. Run the install script:

    bash
    doas bash install.sh

> Moved ./ipfs to /usr/local/bin

  5. Test that Kubo has installed correctly:

    bash
    ipfs --version

> ipfs version 0.43.0

:::

::::

Build Kubo from source

For the current instructions on how to manually download, compile and build Kubo from source, see the Build from Source section in the Kubo repository.

Determining which node to use with the command line

The CLI automatically connects to a running IPFS daemon by reading the $IPFS_PATH/api file (usually ~/.ipfs/api), which contains the RPC API address.

  • Local daemon: Running ipfs daemon creates this file automatically.
  • Remote node: To connect to a daemon on another machine or in a container, see Interact with a remote node.

:::tip
For TLS-secured APIs, see Secure Kubo RPC with TLS and HTTP Auth. If you are just interested in retrieval, see implementation-agnostic HTTP Gateway instead.
:::

Next steps

Now that you've installed IPFS Kubo:

File: docs/install/ipfs-companion.md

title: IPFS Companion

Install the IPFS Companion Browser Extension

IPFS Companion allows you to interact with your IPFS node and the extended IPFS network through your browser. The add-on is available for Brave, Chrome, Edge, Firefox, Opera, and any other Chromium-based web browser.

It enables support for ipfs:// and ipns:// addresses, automatically loads websites and file paths from a local IPFS gateway, allows you to easily import and share a file with IPFS, and more.

Prerequisites

For its full functionality to be enabled, IPFS Companion requires a local IPFS node. As such, it is recommended that you have an IPFS node installed and running on your computer. Any one of the following will satisfy the requirement:

Install

The easiest way to install IPFS Companion is through your browser's specific extensions and add-ons store:

Firefox | Firefox for Android Chrome | Brave | Opera | Edge

Features

IPFS Companion supercharges your browser for the DWeb with features including the following:

Detect URLs with IPFS paths

IPFS Companion detects and tests requests for IPFS-like paths, such as /ipfs/{cid} or /ipns/{peerid_or_host-with-dnslink}, on any website. If a path is a valid IPFS address, it is redirected to load from your local gateway, which converts data from one protocol to another. The gateway at localhost will also automatically switch to a subdomain to provide a unique origin for each website. Providing a unique origin accommodates operations that are restricted to content that shares the same protocol, domain, and port, also known as same-origin content.

https://ipfs.io/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR
โ†’ http://localhost:8080/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR
โ†’ http://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi.ipfs.localhost:8080

IPFS Companion detects DNSLink info in the DNS records of websites. DNSLink is a simple protocol that links content and serviceability from DNS and leverages the DNS distributed architecture. See Glossary > DNSLink. If a site uses DNSLink, IPFS Companion redirects the HTTP request to your local gateway:

http://docs.ipfs.tech
โ†’ http://localhost:8080/ipns/docs.ipfs.tech โ†’ http://docs.ipfs.tech.ipns.localhost:8080/

Toggle redirects globally or per site

You can disable and re-enable local gateway redirects in several ways:

  • Suspend redirects globally in IPFS Companion's preferences.
  • Suspend redirects per site using the toggle under the current tab or in IPFS Companion's preferences.

Access frequently-used IPFS actions from your browser bar

IPFS Companion enables you to quickly and easily access common actions from your browser bar with just a few clicks:

  • See how many peers you're connected with a glance at the cube icon in your browser bar.
  • Check your IPFS API and gateway status by clicking the cube icon to reveal the main menu.
  • Right-click images and other page assets to easily add them to IPFS, including the option to preserve file names.
  • Choose the Quick Import/Share... option in the main menu for quick drag-and-drop import from a browser tab.
  • Pin or unpin IPFS resources directly from the main menu.
  • Copy shareable public gateway links, IPFS content paths, or CIDs of IPFS resources directly from the main menu.
  • Launch the IPFS Web UI dashboard from the main menu with a single click.
  • Toggle gateway redirects or switch all IPFS Companion features on or off quickly and easily from the main menu.

Further documentation

If you want to delve deeper into IPFS Companion, check out the project's documentation at github.com/ipfs/ipfs-companion โ†’

Explore Related Technologies & Topics

View All 9,111+ Repositories โ†’

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#ipfs Browse ipfs catalog โ†’ โšก MCP Servers Model Context Protocol โ†’ ๐Ÿง  Agent Skills Prompt & rule files โ†’ ๐Ÿ”Œ OpenAPI Specs REST & Swagger schemas โ†’