kubo README

The project's README from github.com/ipfs/kubo. As one markdown file: README.md.


Kubo logo
Kubo: IPFS Implementation in Go

The first implementation of IPFS.

Official Part of IPFS Project Discourse Forum Matrix GitHub release

What is Kubo? | Quick Taste | Install | Documentation | Development | Getting Help

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:

$ ipfs init --profile=unixfs-v1-2025
generating ED25519 keypair...done
peer identity: 12D3KooWGcSLQdLDBi2BvoP8WnpdHvhWPbxpGcqkf93rL2XMZK7R

$ ipfs daemon &
Daemon is ready

$ echo "hello IPFS" | ipfs add -q
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/: Docker Image Version (latest semver)

🟢 Release Images

Use these for production deployments.

$ 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

GitHub go.mod Go version

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: Packaging status

[!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 PPA: twdragon
Arch pacman -S kubo Arch package
Fedora COPR: dnf install kubo COPR: taw
Nix nix-env -i kubo nixpkgs unstable
Gentoo emerge -a net-p2p/kubo Gentoo package
openSUSE zypper install kubo openSUSE Tumbleweed
Solus sudo eopkg install kubo Solus package
Guix guix install kubo Guix package
other See Repology for the full list

Snap no longer supported (#8688)

macOS

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

Windows

Manager Install Version
Scoop scoop install kubo Scoop
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:

kubo (ipfs/kubo)

Searching Database…

17.1K ·GitHub
Kubo
这是什么？Kubo 是 IPFS 最早出现、使用最广泛的 Go 语言实现。它是一个守护进程，通过点对点网络存储和分发基于内容寻址的数据，并提供命令行工具（CLI）、WebUI、HTTP 网关以及用于控制它的 HTTP RPC API。
这是我可以嵌入使用的库，还是我自己运行的独立节点？它是一个独立的后台服务（即 'ipfs' 守护进程），运行在你自己的电脑或服务器上，可通过局域网 mDNS 和广域网 Amino DHT 被发现，而不是可以导入应用中的库。
我该如何安装和运行它？获取官方预编译二进制文件或 GitHub Releases，拉取 Docker Hub 上发布的 Docker 镜像，或通过包管理器安装（macOS 上用 Homebrew/MacPorts，Windows 上用 Scoop，Linux 上用 apt、pacman、dnf 等）。
我需要先安装什么特殊的东西吗？不需要单独的运行时，它是一个自包含的 Go 二进制程序。真正的前提是有足够的内存：对于大型 pinset，DHT 重新提供器大约每 2000 万个条目需要 1 GiB 内存。
我能在树莓派这类设备上安全地运行它吗？只能谨慎尝试。资源不足、内存较小的系统可能会出现内存不足（OOM）错误、频繁重启以及漏发数据公告的情况，使你的数据对其他节点部分不可访问。官方提供了针对低内存设备的专门指南。
Kubo 和其他 IPFS 实现有什么区别？Kubo 是最早出现、经过最充分实战检验的 Go 语言实现，注重最大程度的互操作性（UnixFS、HTTP 网关、Bitswap）。README 还提到 Helia，这是一个 JavaScript 实现，适用于浏览器和 Node.js 场景。
我能把 IPFS 内容挂载为本地文件系统吗？可以。Kubo 有一项实验性的 FUSE 功能，可以将 /ipfs、/ipns 和 /mfs（可变文件系统）挂载为普通的本地目录。
我能运行自己的公共网关并过滤内容吗？可以。Kubo 包含一个用于可信及无需信任的内容检索的 HTTP 网关，还有一项内容屏蔽/拒绝列表功能，供公共节点运营者使用。
Kubo 如何在网络上查找数据？它使用 Bitswap 和 HTTP 进行可验证的数据传输，并参与 Amino DHT（另外还有用于委托路由的 HTTP Routing V1 客户端和服务端），以便在各个节点之间通过 CID 定位内容。
What are similar projects?go-ethereum, kryvora-node, canopy, casbin-gateway, sftpgo, mediamtx, ipfs, fabric
Which topics is it in?fuse, ipfs, gateway, filesystem, prometheus, decentralized, p2p, storage, raspberry-pi, http, golang, distributed-systems
Creator
ipfs
Size
59.7 MB
Stars
17.1K
Updated
CommitSep 27Releasev0.43.1Sep 15
Age
12y
Commits · 90 Days