# 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:

  • An IPFS daemon server
  • Extensive command line tooling
  • An HTTP RPC API for controlling the node
  • An HTTP Gateway for serving content to HTTP browsers
  • 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 and adjust using default maximum disk storage (opens new window) 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 (opens new window). New IPFS Kubo binary releases are automatically shown on the Kubo page on dist.ipfs.tech.

If you are unable to access dist.ipfs.tech (opens new window), you can also download Kubo (go-ipfs) from the project's GitHub releases (opens new window) page or /ipns/dist.ipfs.tech at the dweb.link (opens new window) gateway.

Binaries are available for the following operating systems:

OS 32-bit 64-bit ARM ARM-64
macOS No Yes No Yes
FreeBSD Yes Yes Yes No
Linux Yes Yes Yes Yes
OpenBSD Yes Yes Yes No
Windows Yes Yes No No

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

    # Build Kubo from source

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

    # Determining which node to use with the command line

    The command line can detect and use any node that's running, unless it's configured to use an external binary file. Here's which node to use for the local daemon or a remote client:

    # Local daemon

    The local daemon process is automatically started in the CLI with the command ipfs daemon. It creates an $IPFS_PATH/api file with an RPC API address.

    # Remote client

    You can install the standalone IPFS CLI client independently and use it to talk to an IPFS Desktop (Kubo) node. Use the RPC API to talk to the ipfs daemon.

    When an IPFS command executes without parameters, the CLI client checks whether the $IPFS_PATH/api file exists and connects to the address listed there.

    • If an $IPFS_PATH is in the default location (for example, ~/.ipfs on Linux), then it works automatically and the IPFS CLI client talks to the locally running ipfs daemon without any extra configuration.

    • If an $IPFS_PATH isn't in the default location, use the --api <rpc-api-addr> command-line argument. Alternatively, you can set the environment variable to IPFS_PATH. IPFS_PATH will point to a directory with the $IPFS_PATH/api file pointing at the Kubo RPC of the existing ipfs daemon instance.

    # Most common examples

    If you are an IPFS Desktop user, you can install CLI tools and an .ipfs/api file is automatically picked up.

    If you're not running IPFS Desktop, specify a custom port with ipfs --api /ip4/127.0.0.1/tcp/<port> id in the CLI.

    You can use mkdir -p ~/.ipfs && echo "/ip4/<ip>/tcp/<rpc-port>" > ~/.ipfs/api to avoid passing --api every time.

    # Next steps

    Now that you've installed IPFS Kubo:

    • Check out the IPFS Kubo Tutorial in Guides, which will guide you through taking a Kubo node online and interacting with the network.
    • Learn how to quickly install, uninstall, upgrade and downgrade Kubo using ipfs-update.