/ README.md
README.md
1 <h1 align="center"> 2 <br> 3 <a href="https://github.com/ipfs/kubo/blob/master/docs/logo/"><img src="https://user-images.githubusercontent.com/157609/250148884-d6d12db8-fdcf-4be3-8546-2550b69845d8.png" alt="Kubo logo" title="Kubo logo" width="200"></a> 4 <br> 5 Kubo: IPFS Implementation in Go 6 <br> 7 </h1> 8 9 <p align="center" style="font-size: 1.2rem;">The first implementation of IPFS.</p> 10 11 <p align="center"> 12 <a href="https://ipfs.tech"><img src="https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square" alt="Official Part of IPFS Project"></a> 13 <a href="https://discuss.ipfs.tech"><img alt="Discourse Forum" src="https://img.shields.io/discourse/posts?server=https%3A%2F%2Fdiscuss.ipfs.tech"></a> 14 <a href="https://docs.ipfs.tech/community/"><img alt="Matrix" src="https://img.shields.io/matrix/ipfs-space%3Aipfs.io?server_fqdn=matrix.org"></a> 15 <a href="https://github.com/ipfs/kubo/actions"><img src="https://img.shields.io/github/actions/workflow/status/ipfs/kubo/gobuild.yml?branch=master"></a> 16 <a href="https://github.com/ipfs/kubo/releases"><img alt="GitHub release" src="https://img.shields.io/github/v/release/ipfs/kubo?filter=!*rc*"></a> 17 </p> 18 19 <hr /> 20 21 <p align="center"> 22 <b><a href="#what-is-kubo">What is Kubo?</a></b> | <b><a href="#quick-taste">Quick Taste</a></b> | <b><a href="#install">Install</a></b> | <b><a href="#documentation">Documentation</a></b> | <b><a href="#development">Development</a></b> | <b><a href="#getting-help">Getting Help</a></b> 23 </p> 24 25 ## What is Kubo? 26 27 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. 28 29 **Features:** 30 31 - 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)) 32 - [Command-line interface](https://docs.ipfs.tech/reference/kubo/cli/) (`ipfs --help`) 33 - [WebUI](https://github.com/ipfs/ipfs-webui/#readme) for node management 34 - [HTTP Gateway](https://specs.ipfs.tech/http-gateways/) for trusted and [trustless](https://docs.ipfs.tech/reference/http/gateway/#trustless-verifiable-retrieval) content retrieval 35 - [HTTP RPC API](https://docs.ipfs.tech/reference/kubo/rpc/) to control the daemon 36 - [HTTP Routing V1](https://specs.ipfs.tech/routing/http-routing-v1/) client and server for [delegated routing](./docs/delegated-routing.md) 37 - [Content blocking](./docs/content-blocking.md) for public node operators 38 39 **Other IPFS implementations:** [Helia](https://github.com/ipfs/helia) (JavaScript), [more...](https://docs.ipfs.tech/concepts/ipfs-implementations/) 40 41 ## Quick Taste 42 43 After [installing Kubo](#install), verify it works: 44 45 ```console 46 $ ipfs init 47 generating ED25519 keypair...done 48 peer identity: 12D3KooWGcSLQdLDBi2BvoP8WnpdHvhWPbxpGcqkf93rL2XMZK7R 49 50 $ ipfs daemon & 51 Daemon is ready 52 53 $ echo "hello IPFS" | ipfs add -q --cid-version 1 54 bafkreicouv3sksjuzxb3rbb6rziy6duakk2aikegsmtqtz5rsuppjorxsa 55 56 $ ipfs cat bafkreicouv3sksjuzxb3rbb6rziy6duakk2aikegsmtqtz5rsuppjorxsa 57 hello IPFS 58 ``` 59 60 Verify this CID is provided by your node to the IPFS network: <https://check.ipfs.network/?cid=bafkreicouv3sksjuzxb3rbb6rziy6duakk2aikegsmtqtz5rsuppjorxsa> 61 62 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/). 63 64 ## Install 65 66 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). 67 68 Prefer a GUI? Try [IPFS Desktop](https://docs.ipfs.tech/install/ipfs-desktop/) and/or [IPFS Companion](https://docs.ipfs.tech/install/ipfs-companion/). 69 70 ### Minimal System Requirements 71 72 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). 73 74 > [!IMPORTANT] 75 > Larger pinsets require additional memory, with an estimated ~1 GiB of RAM per 20 million items for reproviding to the Amino DHT. 76 77 > [!CAUTION] 78 > 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. 79 80 ### Official Prebuilt Binaries 81 82 Download from https://dist.ipfs.tech#kubo or [GitHub Releases](https://github.com/ipfs/kubo/releases/latest). 83 84 ### Docker 85 86 Official images are published at https://hub.docker.com/r/ipfs/kubo/: [](https://hub.docker.com/r/ipfs/kubo/) 87 88 #### 🟢 Release Images 89 90 Use these for production deployments. 91 92 - `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) 93 - [`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) 94 95 ```console 96 $ docker pull ipfs/kubo:latest 97 $ docker run --rm -it --net=host ipfs/kubo:latest 98 ``` 99 100 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`. 101 102 #### 🟠Developer Preview Images 103 104 For internal testing, not intended for production. 105 106 - [`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/) 107 - [`master-YYYY-DD-MM-GITSHA`](https://hub.docker.com/r/ipfs/kubo/tags?name=master-2) points at a specific commit 108 109 #### 🔴 Internal Staging Images 110 111 For testing arbitrary commits and experimental patches (force push to `staging` branch). 112 113 - [`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/) 114 - [`staging-YYYY-DD-MM-GITSHA`](https://hub.docker.com/r/ipfs/kubo/tags?name=staging-2) points at a specific commit 115 116 ### Build from Source 117 118  119 120 ```bash 121 git clone https://github.com/ipfs/kubo.git 122 cd kubo 123 make build # creates cmd/ipfs/ipfs 124 make install # installs to $GOPATH/bin/ipfs 125 ``` 126 127 See the [Developer Guide](docs/developer-guide.md) for details, Windows instructions, and troubleshooting. 128 129 ### Package Managers 130 131 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) 132 133 > [!WARNING] 134 > 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). 135 136 #### Linux 137 138 | Distribution | Install | Version | 139 |--------------|---------|---------| 140 | Ubuntu | [PPA](https://launchpad.net/~twdragon/+archive/ubuntu/ipfs): `sudo apt install ipfs-kubo` | [](https://launchpad.net/~twdragon/+archive/ubuntu/ipfs) | 141 | Arch | `pacman -S kubo` | [](https://archlinux.org/packages/extra/x86_64/kubo/) | 142 | Fedora | [COPR](https://copr.fedorainfracloud.org/coprs/taw/ipfs/): `dnf install kubo` | [](https://copr.fedorainfracloud.org/coprs/taw/ipfs/) | 143 | Nix | `nix-env -i kubo` | [](https://search.nixos.org/packages?query=kubo) | 144 | Gentoo | `emerge -a net-p2p/kubo` | [](https://packages.gentoo.org/packages/net-p2p/kubo) | 145 | openSUSE | `zypper install kubo` | [](https://software.opensuse.org/package/kubo) | 146 | Solus | `sudo eopkg install kubo` | [](https://packages.getsol.us/shannon/k/kubo/) | 147 | Guix | `guix install kubo` | [](https://packages.guix.gnu.org/packages/kubo/) | 148 | _other_ | [See Repology for the full list](https://repology.org/project/kubo/versions) | | 149 150 ~~Snap~~ no longer supported ([#8688](https://github.com/ipfs/kubo/issues/8688)) 151 152 #### macOS 153 154 | Manager | Install | Version | 155 |---------|---------|---------| 156 | Homebrew | `brew install ipfs` | [](https://formulae.brew.sh/formula/ipfs) | 157 | MacPorts | `sudo port install ipfs` | [](https://ports.macports.org/port/ipfs/) | 158 | Nix | `nix-env -i kubo` | [](https://search.nixos.org/packages?query=kubo) | 159 | _other_ | [See Repology for the full list](https://repology.org/project/kubo/versions) | | 160 161 #### Windows 162 163 | Manager | Install | Version | 164 |---------|---------|---------| 165 | Scoop | `scoop install kubo` | [](https://scoop.sh/#/apps?q=kubo) | 166 | _other_ | [See Repology for the full list](https://repology.org/project/kubo/versions) | | 167 168 ~~Chocolatey~~ no longer supported ([#9341](https://github.com/ipfs/kubo/issues/9341)) 169 170 ## Documentation 171 172 | Topic | Description | 173 |-------|-------------| 174 | [Configuration](docs/config.md) | All config options reference | 175 | [Environment variables](docs/environment-variables.md) | Runtime settings via env vars | 176 | [Experimental features](docs/experimental-features.md) | Opt-in features in development | 177 | [HTTP Gateway](docs/gateway.md) | Path, subdomain, and trustless gateway setup | 178 | [HTTP RPC clients](docs/http-rpc-clients.md) | Client libraries for Go, JS | 179 | [Delegated routing](docs/delegated-routing.md) | Multi-router and HTTP routing | 180 | [Metrics & monitoring](docs/metrics.md) | Prometheus metrics | 181 | [Content blocking](docs/content-blocking.md) | Denylist for public nodes | 182 | [Customizing](docs/customizing.md) | Unsure if use Plugins, Boxo, or fork? | 183 | [Debug guide](docs/debug-guide.md) | CPU profiles, memory analysis, tracing | 184 | [Changelogs](docs/changelogs/) | Release notes for each version | 185 | [All documentation](https://github.com/ipfs/kubo/tree/master/docs) | Full list of docs | 186 187 ## Development 188 189 See the [Developer Guide](docs/developer-guide.md) for build instructions, testing, and contribution workflow. AI coding agents should follow [AGENTS.md](AGENTS.md). 190 191 ## Getting Help 192 193 - [IPFS Forum](https://discuss.ipfs.tech) - community support, questions, and discussion 194 - [Community](https://docs.ipfs.tech/community/) - chat, events, and working groups 195 - [GitHub Issues](https://github.com/ipfs/kubo/issues) - bug reports for Kubo specifically 196 - [IPFS Docs Issues](https://github.com/ipfs/ipfs-docs/issues) - documentation issues 197 198 ## Security Issues 199 200 See [`SECURITY.md`](SECURITY.md). 201 202 ## Contributing 203 204 [](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) 205 206 We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Developer Guide](docs/developer-guide.md). 207 208 This repository follows the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md). 209 210 ## Maintainer Info 211 212 <a href="https://ipshipyard.com/"><img align="right" src="https://github.com/user-attachments/assets/39ed3504-bb71-47f6-9bf8-cb9a1698f272" /></a> 213 214 > [!NOTE] 215 > Kubo is maintained by the [Shipyard](https://ipshipyard.com/) team. 216 > 217 > [Release Process](https://ipshipyard.notion.site/Kubo-Release-Process-6dba4f5755c9458ab5685eeb28173778) 218 219 ## License 220 221 Dual-licensed under Apache 2.0 and MIT: 222 223 - [LICENSE-APACHE](LICENSE-APACHE) 224 - [LICENSE-MIT](LICENSE-MIT)