## 1. Project Overview & Quickstart (ipfs/kubo)
## File: README.md
[](https://github.com/ipfs/kubo/blob/master/docs/logo/)
Kubo: IPFS Implementation in Go
## What is Kubo?
Kubo was the first [IPFS](https://docs.ipfs.tech/concepts/what-is-ipfs/) implementation and is the [most widely used one today](https://probelab.io/ipfs/topology/#chart-agent-types-avg). It takes an opinionated approach to content-addressing ([CIDs](https://docs.ipfs.tech/concepts/glossary/#cid), [DAGs](https://docs.ipfs.tech/concepts/glossary/#dag)) that maximizes interoperability: [UnixFS](https://docs.ipfs.tech/concepts/glossary/#unixfs) for files and directories, [HTTP Gateways](https://docs.ipfs.tech/concepts/glossary/#gateway) for web browsers, [Bitswap](https://docs.ipfs.tech/concepts/glossary/#bitswap) and [HTTP](https://specs.ipfs.tech/http-gateways/trustless-gateway/) for verifiable data transfer.
**Features:**
- Runs an IPFS node as a network service (LAN [mDNS](https://github.com/libp2p/specs/blob/master/discovery/mdns.md) and WAN [Amino DHT](https://docs.ipfs.tech/concepts/glossary/#dht))
- [Command-line interface](https://docs.ipfs.tech/reference/kubo/cli/) (`ipfs --help`)
- [WebUI](https://github.com/ipfs/ipfs-webui/#readme) for node management
- [HTTP Gateway](https://specs.ipfs.tech/http-gateways/) for trusted and [trustless](https://docs.ipfs.tech/reference/http/gateway/#trustless-verifiable-retrieval) content retrieval
- [HTTP RPC API](https://docs.ipfs.tech/reference/kubo/rpc/) to control the daemon
- [HTTP Routing V1](https://specs.ipfs.tech/routing/http-routing-v1/) client and server for [delegated routing](./docs/delegated-routing.md)
- [FUSE mounts](./docs/fuse.md) for mounting `/ipfs`, `/ipns`, and `/mfs` as local filesystems (experimental)
- [Content blocking](./docs/content-blocking.md) for public node operators
**Other IPFS implementations:** [Helia](https://github.com/ipfs/helia) (JavaScript), [more...](https://docs.ipfs.tech/concepts/ipfs-implementations/)
## Quick Taste
After [installing Kubo](#install), 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:
See `ipfs add --help` for all import options. Ready for more? Follow the [command-line quick start](https://docs.ipfs.tech/how-to/command-line-quick-start/).
## Install
Follow the [official installation guide](https://docs.ipfs.tech/install/command-line/), or choose: [prebuilt binary](#official-prebuilt-binaries) | [Docker](#docker) | [package manager](#package-managers) | [from source](#build-from-source).
Prefer a GUI? Try [IPFS Desktop](https://docs.ipfs.tech/install/ipfs-desktop/) and/or [IPFS Companion](https://docs.ipfs.tech/install/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](docs/production/low-memory.md).
### Official Prebuilt Binaries
Download from https://dist.ipfs.tech#kubo or [GitHub Releases](https://github.com/ipfs/kubo/releases/latest).
### Docker
Official images are published at https://hub.docker.com/r/ipfs/kubo/: [](https://hub.docker.com/r/ipfs/kubo/)
#### 🟢 Release Images
Use these for production deployments.
- `latest` and [`release`](https://hub.docker.com/r/ipfs/kubo/tags?name=release) always point at [the latest stable release](https://github.com/ipfs/kubo/releases/latest)
- [`vN.N.N`](https://hub.docker.com/r/ipfs/kubo/tags?name=v) points at a specific [release tag](https://github.com/ipfs/kubo/releases)
```console
$ docker pull ipfs/kubo:latest
$ docker run --rm -it --net=host ipfs/kubo:latest
```
To [customize your node](https://docs.ipfs.tech/install/run-ipfs-inside-docker/#customizing-your-node), pass config via `-e` or mount scripts in `/container-init.d`.
#### đźź Developer Preview Images
For internal testing, not intended for production.
- [`master-latest`](https://hub.docker.com/r/ipfs/kubo/tags?name=master-latest) points at `HEAD` of [`master`](https://github.com/ipfs/kubo/commits/master/)
- [`master-YYYY-DD-MM-GITSHA`](https://hub.docker.com/r/ipfs/kubo/tags?name=master-2) points at a specific commit
#### đź”´ Internal Staging Images
For testing arbitrary commits and experimental patches (force push to `staging` branch).
- [`staging-latest`](https://hub.docker.com/r/ipfs/kubo/tags?name=staging-latest) points at `HEAD` of [`staging`](https://github.com/ipfs/kubo/commits/staging/)
- [`staging-YYYY-DD-MM-GITSHA`](https://hub.docker.com/r/ipfs/kubo/tags?name=staging-2) points at a specific commit
### 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](docs/developer-guide.md) 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](https://repology.org/project/kubo/versions) for the full list: [](https://repology.org/project/kubo/versions)
> [!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](#build-from-source).
#### Linux
| Distribution | Install | Version |
|--------------|---------|---------|
| Ubuntu | [PPA](https://launchpad.net/~twdragon/+archive/ubuntu/ipfs): `sudo apt install ipfs-kubo` | [](https://launchpad.net/~twdragon/+archive/ubuntu/ipfs) |
| Arch | `pacman -S kubo` | [](https://archlinux.org/packages/extra/x86_64/kubo/) |
| Fedora | [COPR](https://copr.fedorainfracloud.org/coprs/taw/ipfs/): `dnf install kubo` | [](https://copr.fedorainfracloud.org/coprs/taw/ipfs/) |
| Nix | `nix-env -i kubo` | [](https://search.nixos.org/packages?query=kubo) |
| Gentoo | `emerge -a net-p2p/kubo` | [](https://packages.gentoo.org/packages/net-p2p/kubo) |
| openSUSE | `zypper install kubo` | [](https://software.opensuse.org/package/kubo) |
| Solus | `sudo eopkg install kubo` | [](https://packages.getsol.us/shannon/k/kubo/) |
| Guix | `guix install kubo` | [](https://packages.guix.gnu.org/packages/kubo/) |
| _other_ | [See Repology for the full list](https://repology.org/project/kubo/versions) | |
~~Snap~~ no longer supported ([#8688](https://github.com/ipfs/kubo/issues/8688))
#### macOS
| Manager | Install | Version |
|---------|---------|---------|
| Homebrew | `brew install ipfs` | [](https://formulae.brew.sh/formula/ipfs) |
| MacPorts | `sudo port install ipfs` | [](https://ports.macports.org/port/ipfs/) |
| Nix | `nix-env -i kubo` | [](https://search.nixos.org/packages?query=kubo) |
| _other_ | [See Repology for the full list](https://repology.org/project/kubo/versions) | |
#### Windows
| Manager | Install | Version |
|---------|---------|---------|
| Scoop | `scoop install kubo` | [](https://scoop.sh/#/apps?q=kubo) |
| _other_ | [See Repology for the full list](https://repology.org/project/kubo/versions) | |
~~Chocolatey~~ no longer supported ([#9341](https://github.com/ipfs/kubo/issues/9341))
## Documentation
| Topic | Description |
|-------|-------------|
| [Configuration](docs/config.md) | All config options reference |
| [Environment variables](docs/environment-variables.md) | Runtime settings via env vars |
| [Experimental features](docs/experimental-features.md) | Opt-in features in development |
| [HTTP Gateway](docs/gateway.md) | Path, subdomain, and trustless gateway setup |
| [HTTP RPC clients](docs/http-rpc-clients.md) | Client libraries for Go, JS |
| [Delegated routing](docs/delegated-routing.md) | Multi-router and HTTP routing |
| [Metrics & monitoring](docs/metrics.md) | Prometheus metrics |
| [FUSE mounts](docs/fuse.md) | Mount `/ipfs`, `/ipns`, `/mfs` as local filesystems |
| [Content blocking](docs/content-blocking.md) | Denylist for public nodes |
| [Customizing](docs/customizing.md) | Unsure if use Plugins, Boxo, or fork? |
| [Debug guide](docs/debug-guide.md) | CPU profiles, memory analysis, tracing |
| [Changelogs](docs/changelogs/) | Release notes for each version |
| [All documentation](https://github.com/ipfs/kubo/tree/master/docs) | Full list of docs |
## Development
See the [Developer Guide](docs/developer-guide.md) for build instructions, testing, and contribution workflow. AI coding agents should follow [AGENTS.md](AGENTS.md).
## Getting Help
- [IPFS Forum](https://discuss.ipfs.tech) - community support, questions, and discussion
- [Community](https://docs.ipfs.tech/community/) - chat, events, and working groups
- [GitHub Issues](https://github.com/ipfs/kubo/issues) - bug reports for Kubo specifically
- [IPFS Docs Issues](https://github.com/ipfs/ipfs-docs/issues) - documentation issues
## Security Issues
See [`SECURITY.md`](SECURITY.md).
## Contributing
[](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)
We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Developer Guide](docs/developer-guide.md).
This repository follows the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
## Maintainer Info
[](https://ipshipyard.com/)
> [!NOTE]
> Kubo is maintained by the [Shipyard](https://ipshipyard.com/) team.
>
> [Release Process](https://ipshipyard.notion.site/Kubo-Release-Process-6dba4f5755c9458ab5685eeb28173778)
## License
Dual-licensed under Apache 2.0 and MIT:
- [LICENSE-APACHE](LICENSE-APACHE)
- [LICENSE-MIT](LICENSE-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`](https://pkg.go.dev/github.com/ipfs/kubo/core/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
```
λ. 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:
ipfs bootstrap >bootstrap_peers
ipfs bootstrap rm --all
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 `` 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 ` now wraps directories @jbenet
* `ipfs add -w ` 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 ` 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
- [Project set up](#project-set-up)
- [Run locally](#run-locally)
- [Troubleshooting](#troubleshooting)
- [Digital envelope routines initialization error](#digital-envelope-routines-initialization-error)
- [Contribute to documentation](#contribute-to-documentation)
- [Issues](#issues)
- [Bounties](#bounties)
- [Suggestions](#suggestions)
- [Pull requests welcome](#pull-requests-welcome)
- [Style and configuration guide](#style-and-configuration-guide)
- [Static-site generator](#static-site-generator)
- [Automated deployments](#automated-deployments)
- [Translation](#translation)
- [License](#license)
---
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](https://docs.ipfs.tech).**
## 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
```
1. Move into the `ipfs-docs` folder:
```bash
cd ipfs-docs
```
1. Install the NPM dependencies:
```bash
npm install
```
1. Boot up the application in _dev mode_:
```bash
npm start
```
1. Open `http://localhost:8080` in your browser.
1. Close the local server with `CTRL` + `c`.
1. 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](#project-set-up) section above and continue with the steps. You can also check [this issue in the Webpack GitHub repository](https://github.com/webpack/webpack/issues/14532) 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](https://github.com/ipfs/devgrants/blob/main/BOUNTIES.md)!
### Issues
If you find something wrong within this repository, please raise an issue [here →](https://github.com/ipfs/ipfs-docs/issues). 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](https://github.com/ipfs/ipfs-docs/issues?q=is%3Aopen+is%3Aissue+label%3Abounty). Submissions must be production-ready and meet all the specifications listed on the issue page. To get started, check out [IPFS Bounties](https://github.com/ipfs/devgrants/blob/main/BOUNTIES.md).
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](https://github.com/ipfs/ipfs-docs/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Fquestion).
### 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](https://vuepress.vuejs.org/) to convert the Markdown guides into a documentation website. All the documentation is written in Markdown; follow the [VuePress Markdown documentation](https://vuepress.github.io/guide/markdown.html) 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](https://github.com/ipfs/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**](https://creativecommons.org/licenses/by/4.0/).
---
## 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](#ipfs-retrieval-methods)
- [Verified vs. trusted CID retrieval](#verified-vs-trusted-cid-retrieval)
- [Fetching the CID with Kubo](#fetching-the-cid-with-kubo)
- [Fetching the CID with Python and ipfsspec](#fetching-the-cid-with-python-and-ipfsspec)
- [Fetching the CID with an IPFS Gateway](#fetching-the-cid-with-an-ipfs-gateway)
- [Summary and next steps](#summary-and-next-steps)
## IPFS retrieval methods
There are two primary ways to retrieve files and directories published to IPFS:
- Use an [**IPFS node**](../concepts/nodes.md) by installing one of the IPFS implementations, e.g. [Kubo](../concepts/nodes.md#kubo) on your computer. This allows you to fetch and verify CIDs from other nodes in the IPFS network.
- Use an [**IPFS Gateway**](../concepts/ipfs-gateway.md), 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](../install/command-line.md), 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]`](../reference/kubo/cli.md#ipfs-get) 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](https://www.npmjs.com/package/@helia/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](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), accepting CIDs instead of URLs, returning [Response](https://developer.mozilla.org/en-US/docs/Web/API/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](https://codepen.io/2color))
on [CodePen](https://codepen.io).
:::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](https://github.com/fsspec/ipfsspec) is a read-only [fsspec](https://filesystem-spec.readthedocs.io/) implementation for IPFS. It performs **verified** HTTP retrieval from gateways by fetching [CAR files](../concepts/glossary.md#car) 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
```
1. 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](https://github.com/ipfs/specs/pull/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:
- [https://ipfs.io/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4](https://ipfs.io/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4)
- [https://dweb.link/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4](https://dweb.link/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4)
- [https://inbrowser.link/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4](https://inbrowser.link/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4)
> `inbrowser.link` is powered by the [Service Worker Gateway](https://github.com/ipfs/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](./pin.md) using an IPFS Kubo node and an IPFS Gateway.
Possible next steps include:
- Learn more about [how IPFS works](../concepts/how-ipfs-works.md) and [the lifecycle of data in IPFS](../concepts/lifecycle.md).
---
## 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](https://gameofthrones.fandom.com/wiki/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](https://github.com/ipfs/ipfs) 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](https://github.com/jbenet) 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](https://git-scm.com/) manages software versioning and collaboration through a data-linking structure known as a [Merkle tree](https://en.wikipedia.org/wiki/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](https://www.bittorrent.com/) 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](https://filecoin.io/), as the first projects. Protocol Labs was modeled to be like an independent [Bell Labs](https://www.bell-labs.com/about/history-bell-labs/) (outside of the IPFS ecosystem, Protocol Labs has since spawned projects including [Coinlist](https://coinlist.co/), [The SAFT Project](https://saftproject.com/), and [SourceCred](https://sourcecred.io/)).
Protocol Labs entered the [Y Combinator Summer 2014 Class](https://www.ycombinator.com/companies/). Juan got to work writing code and the [IPFS whitepaper](https://ipfs.io/ipfs/QmR7GSQM93Cx5eAg6a6yRzNde1FQv7uL6X1o4k7zrJa3LX/ipfs.draft3.pdf).
The whitepaper was published in July 2014. It caught the attention of P2P and internet enthusiasts, including Jeromy Johnson (aka [whyrusleeping](https://github.com/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](https://web.archive.org/web/20230520184851/https://philzcoffee.com/menu/coffee) FTW!) to create the alpha release of [Kubo](https://github.com/ipfs/kubo/blob/master/CHANGELOG.md#023---2015-03-01). 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](https://bitcoin.org/bitcoin.pdf) had ushered in a renaissance of P2P innovation. A P2P summer was in full swing. IPFS gained usage in the [Ethereum](https://ethereum.org/) and wider blockchain communities. In September 2015, [Neocities](https://neocities.org/) became the first major site to [implement IPFS in production](https://blog.neocities.org/blog/2015/09/08/its-time-for-the-distributed-web.html).
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](https://multiformats.io/), [libp2p](https://libp2p.io/), and [IPLD](https://ipld.io/) were spun out as separate projects from IPFS. The IPFS team attended and hosted many community gatherings highlighted by the [Decentralized Web Summit](https://2016.decentralizedweb.net/).
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](https://github.com/Kubuxu)), an IPFS software engineer, took it upon himself to download the Turkish version of Wikipedia and [put the snapshot onto IPFS](https://blog.ipfs.tech/24-uncensorable-wikipedia/) 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](https://coinlist.co/filecoin). 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](https://en.wikipedia.org/wiki/Uncle_Ben#%22With_great_power_comes_great_responsibility%22), 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](https://2019.ipfs.camp) in Barcelona in June. The retreat brought together 150 distributed-web pioneers to learn, collaborate, and build. It inspired a [successful collaboration](https://blog.ipfs.tech/2020-02-14-improved-bitswap-for-container-distribution/) 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](https://github.com/ipfs/kubo/blob/master/docs/changelogs/v0.5.md) 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](https://ecosystem.ipfs.tech/), reliability is just as important as speed. For that, Protocol Labs developed, used, and released [Testground](https://blog.ipfs.tech/2020-05-06-launching-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](https://blog.ipfs.tech/2020-03-30-ipfs-in-opera-for-android/), [Microsoft ION](https://techcommunity.microsoft.com/t5/azure-active-directory-identity/toward-scalable-decentralized-identifier-systems/ba-p/560168), and [Cloudflare](https://blog.cloudflare.com/distributed-web-gateway) 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](https://github.com/ipfs/community/blob/master/code-of-conduct.md). Please contact [abuse@ipfs.tech](mailto:abuse@ipfs.tech) 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](https://about.ipfs.io/#reporting-abuse).
:::
The community and ecosystem around the IPFS project is large, diverse, and abounds with opportunities for involvement. Learn more in the [Community section](../community/README.md).
## History of IPFS
Want to know how it all began? Learn the [history of the IPFS project](history.md).
## 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](repository-guide.md).
## IPFS specifications
[Technical specifications](https://github.com/ipfs/specs) 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](https://github.com/ipfs/notes).
## Related projects
IPFS is a highly modular project that is itself made out of many different protocols and tools. Learn more about the [IPFS-related projects](related-projects.md) 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](../community/contribute/ways-to-contribute.md).
---
## File: docs/project/related-projects.md
---
title: Related projects
---
# Related projects
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](https://protocol.ai). 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/](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/](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/](https://ipfscluster.io/).
## DNSLink
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/](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/](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/](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:
- [Fetching or contributing to IPFS code](#fetch-or-contribute-to-ipfs-code)
- [Participating in IPFS project operations](#participate-in-ipfs-project-operations)
## 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](https://github.com/ipfs/js-ipfs) was archived in 2023 in favor of [Helia](https://github.com/ipfs/helia), a leaner, more modular, modern implementation of IPFS in JavaScript. See the [deprecation announcement](https://blog.ipfs.tech/202305-js-ipfs-deprecation-for-helia/) for the migration path.
Any js-ipfs tutorial you find is out of date. Use Helia instead.
:::
- [Kubo](https://github.com/ipfs/kubo): The reference implementation written in Go.
- [Helia](https://github.com/ipfs/helia): The JavaScript and TypeScript implementation of IPFS.
- [rust-ipfs](https://github.com/dariusc93/rust-ipfs): Implementation in Rust.
- [Other implementations](../concepts/ipfs-implementations.md): Up-to-date links to all other protocol implementations.
### Client implementations
- [Current list](https://github.com/ipfs/ipfs#http-client-libraries) of HTTP client libraries.
### Underlying components
| Subsystem | Go | JavaScript | Rust |
|------------|---------------------------------------------------------------------------------------|-------------------------------------------------|------------------------------------------------|
| [LibP2P](https://github.com/libp2p) | [ go-libp2p ]( https://github.com/libp2p/go-libp2p ) | [js-libp2p](https://github.com/libp2p/js-libp2p) | [rust-libp2p](https://github.com/libp2p/rust-libp2p) |
| [IPLD](https://github.com/ipld) | [ go-ipld ]( https://github.com/ipld/go-ipld ), [go-ipld-prime](https://github.com/ipld/go-ipld-prime) | [js-ipld](https://github.com/ipld/js-ipld) | [libipld](https://github.com/ipld/libipld) |
| IPNS | [go-ipns](https://github.com/ipfs/go-ipns) | [js-ipns](https://github.com/ipfs/js-ipns) | [rust-ipns](https://lib.rs/crates/rust-ipns) |
| [Multiaddr](https://github.com/multiformats/multiaddr) | [go-multiaddr](https://github.com/multiformats/go-multiaddr) | [js-multiaddr](https://github.com/multiformats/js-multiaddr) | [rust-multiaddr](https://github.com/multiformats/rust-multiaddr) |
| [Multicodec](https://github.com/multiformats/multicodec) | [go-multicodec](https://github.com/multiformats/go-multicodec) | [js-multiformats](https://github.com/multiformats/js-multiformats) | N/A |
| [Multihash](https://github.com/multiformats/multihash) | [go-multihash](https://github.com/multiformats/go-multihash) | [js-multiformats](https://github.com/multiformats/js-multiformats) | [rust-multihash](https://github.com/multiformats/rust-multihash) |
| [Multibase](https://github.com/multiformats/multibase) | [go-multibase](https://github.com/multiformats/go-multibase) | [js-multiformats](https://github.com/multiformats/js-multiformats) | [rust-multibase](https://github.com/multiformats/rust-multibase) |
| CID | N/A | [js-multiformats](https://github.com/multiformats/js-multiformats) | [rust-cid](https://github.com/multiformats/rust-cid) |
### IPFS tools and products
- [IPFS Cluster](https://github.com/ipfs/ipfs-cluster): Automatically allocate, replicate, and track your data as a global pinset distributed among a swarm of peers.
- [IPFS Companion](https://github.com/ipfs/ipfs-companion): The IPFS web browser extension.
- [IPFS Web UI](https://github.com/ipfs/ipfs-webui): An easy-to-use web interface for IPFS nodes.
- [IPFS Desktop](https://github.com/ipfs/ipfs-desktop): Standalone IPFS app with an easy-to-use node interface, plus menubar/tray shortcuts
- [ipfs-gui](https://github.com/ipfs/ipfs-gui): Coordinating development, user experience, and maintenance of IPFS GUIs.
- [IPFS Shipyard](https://github.com/ipfs-shipyard): GitHub org showcasing incubated projects of all types created by the global IPFS community.
### Interoperability, platforms, and standards
- [IPFS Web Browsers Integration](https://github.com/ipfs/in-web-browsers): Tracking progress toward native IPFS support in web browsers.
- [Are We Distributed Yet?](https://github.com/arewedistributedyet/arewedistributedyet): Prioritized listing of progress toward making peer-to-peer a first-class part of the web.
- [IPFS Mobile Design Guidelines](https://github.com/ipfs/mobile-design-guidelines): Best practices for making IPFS work for mobile.
- [Interoperability Tests for IPFS](https://github.com/ipfs/interop): On-the-wire interop for IPFS.
## 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
- [IPFS Project Roadmap](https://github.com/ipfs/roadmap)
- [IPFS Specifications](https://github.com/ipfs/specs)
- [IPFS Infrastructure](https://github.com/ipfs/infra)
### Internationalization
- [i18n](https://github.com/ipfs-shipyard/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:
- Runs an IPFS-Node as a network service that is part of LAN and WAN ([Amino](https://probelab.io/ipfs/amino/)) DHT
- [HTTP Gateway](https://specs.ipfs.tech/http-gateways/) (`/ipfs` and `/ipns`) functionality for trusted and [trustless](https://docs.ipfs.tech/reference/http/gateway/#trustless-verifiable-retrieval) content retrieval
- [HTTP Routing V1](https://specs.ipfs.tech/routing/http-routing-v1/) (`/routing/v1`) client and server implementation for [delegated routing](https://github.com/ipfs/kubo/blob/master/docs/delegated-routing.md) lookups
- [HTTP Kubo RPC API](https://docs.ipfs.tech/reference/kubo/rpc/) (`/api/v0`) to access and control the daemon
- [Command Line Interface](https://docs.ipfs.tech/reference/kubo/cli/) (`ipfs --help`) based on (`/api/v0`) RPC API
- [WebUI](https://github.com/ipfs/ipfs-webui/#readme) to manage the Kubo node
- [Content blocking](https://github.com/ipfs/kubo/blob/master/docs/content-blocking.md) support for operators of public nodes
- Binaries for Windows, MacOS, Linux, FreeBSD and OpenBSD
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](../reference/kubo/cli.md#ipfs-daemon) and adjust using [default maximum disk storage](https://github.com/ipfs/kubo/blob/v0.43.0/docs/config.md#datastorestoragemax) 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](https://dist.ipfs.tech#kubo). 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](https://dist.ipfs.tech#kubo), you can also download Kubo from the project's GitHub [releases](https://github.com/ipfs/kubo/releases/latest) page or `/ipns/dist.ipfs.tech` at the [dweb.link](https://dweb.link/ipns/dist.ipfs.tech#kubo) 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`](https://dist.ipfs.tech/#kubo).
```bash
wget https://dist.ipfs.tech/kubo/v0.43.0/kubo_v0.43.0_linux-amd64.tar.gz
```
1. 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
```
1. Move into the `kubo` folder:
```bash
cd kubo
```
1. Run the installation script
```bash
sudo bash install.sh
> Moved ./ipfs to /usr/local/bin
```
1. 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`](https://dist.ipfs.tech/#kubo).
```powershell
wget https://dist.ipfs.tech/kubo/v0.43.0/kubo_v0.43.0_windows-amd64.zip -Outfile kubo_v0.43.0.zip
```
1. 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
```
1. Move into the `kubo_v0.43.0` folder
```powershell
cd ~\Apps\kubo_v0.43.0\kubo
```
1. 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:
1. Save the current working directory into a temporary variable:
```powershell
$GO_IPFS_LOCATION = pwd
```
1. 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
```
1. 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')"
```
1. Load your `$PROFILE`:
```powershell
& $profile
```
1. Navigate to your home folder
```powershell
cd ~
```
1. 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](https://dist.ipfs.tech/kubo/v0.21.0/).
1. Navigate to a terminal.
1. Use `brew` to install Kubo:
```shell
brew install ipfs
```
1. 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`](https://dist.ipfs.tech/#kubo).
```bash
wget https://dist.ipfs.tech/kubo/v0.43.0/kubo_v0.43.0_freebsd-amd64.tar.gz
```
1. 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
```
1. Move into the `kubo` folder:
```bash
cd kubo
```
1. Run the install script:
```bash
doas bash install.sh
> Moved ./ipfs to /usr/local/bin
```
1. 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`](https://dist.ipfs.tech/#kubo).
```bash
wget https://dist.ipfs.tech/kubo/v0.43.0/kubo_v0.43.0_openbsd-amd64.tar.gz
```
1. 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
```
1. Move into the `kubo` folder:
```bash
cd kubo
```
1. Run the install script:
```bash
doas bash install.sh
> Moved ./ipfs to /usr/local/bin
```
1. 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](https://github.com/ipfs/kubo/blob/v0.43.0/README.md#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](../reference/kubo/rpc.md) 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](../how-to/command-line-quick-start.md#interact-with-a-remote-node).
:::tip
For TLS-secured APIs, see [Secure Kubo RPC with TLS and HTTP Auth](../how-to/kubo-rpc-tls-auth.md). If you are just interested in retrieval, see implementation-agnostic [HTTP Gateway](../reference/http/gateway.md) instead.
:::
## Next steps
Now that you've installed IPFS Kubo:
- Check out the [IPFS Kubo Tutorial in Guides](../how-to/command-line-quick-start.md), which will guide you through taking a Kubo node online and interacting with the network.
---
## 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 IPFS Desktop App](../install/ipfs-desktop.md)
- [Install IPFS Kubo CLI and Daemon](../install/command-line.md)
## Install
The easiest way to install IPFS Companion is through your browser's specific extensions and add-ons store:
| [Firefox](https://www.mozilla.org/firefox/new/) \| [Firefox for Android](https://play.google.com/store/apps/details?id=org.mozilla.firefox) | [Chrome](https://www.google.com/chrome/) \| [Brave](https://brave.com/) \| [Opera](https://www.opera.com/) \| [Edge](https://www.microsoftedgeinsider.com/) |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [](https://addons.mozilla.org/firefox/addon/ipfs-companion/) | [](https://chrome.google.com/webstore/detail/ipfs-companion/nibjojkomfdiaoajekhjakgkdhaomnch) |
## 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://en.wikipedia.org/wiki/Same-origin_policy#:~:text=In%20computing%2C%20the%20same%2Dorigin,pages%20have%20the%20same%20origin).
> `https://ipfs.io/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR`
> → `http://localhost:8080/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR`
> → `http://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi.ipfs.localhost:8080`
### Detect DNSLink-enabled URLs
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](../concepts/glossary.md#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](https://github.com/ipfs/ipfs-webui) 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 →](https://github.com/ipfs/ipfs-companion)