Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


IPFS implementation in go

Subscribe to updates I use go-ipfs

Statistics on go-ipfs

Number of watchers on Github 4813
Number of open issues 875
Average time to close an issue 21 days
Main language Go
Average time to merge a PR 2 days
Open pull requests 291+
Closed pull requests 81+
Last commit over 1 year ago
Repo Created over 5 years ago
Repo Last Updated over 1 year ago
Size 28.3 MB
Organization / Authoripfs
Page Updated
Do you use go-ipfs? Leave a review!
View open issues (875)
View go-ipfs activity
View on github
Fresh, new opensource launches ๐Ÿš€๐Ÿš€๐Ÿš€
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating go-ipfs for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)



standard-readme compliant GoDoc Build Status

Throughput Graph

IPFS implementation in Go

IPFS is a global, versioned, peer-to-peer filesystem. It combines good ideas from Git, BitTorrent, Kademlia, SFS, and the Web. It is like a single bittorrent swarm, exchanging git objects. IPFS provides an interface as simple as the HTTP web, but with permanence built in. You can also mount the world at /ipfs.

For more info see:

Please put all issues regarding IPFS design in the ipfs repo issues. Please put all issues regarding the Go IPFS implementation in this repo.

Table of Contents

Security Issues

The IPFS protocol and its implementations are still in heavy development. This means that there may be problems in our protocols, or there may be mistakes in our implementations. And -- though IPFS is not production-ready yet -- many people are already running nodes in their machines. So we take security vulnerabilities very seriously. If you discover a security issue, please bring it to our attention right away!

If you find a vulnerability that may affect live deployments -- for example, by exposing a remote execution exploit -- please send your report privately to Please DO NOT file a public issue. The GPG key for is 4B9665FB 92636D17 7C7A86D3 50AAE8A9 59B13AF3.

If the issue is a protocol weakness that cannot be immediately exploited or something not yet deployed, just discuss it openly.


The canonical download instructions for IPFS are over at: It is highly suggested you follow those instructions if you are not interested in working on IPFS development.

Install prebuilt packages

We host prebuilt binaries over at our distributions page.

From there:

  • Click the blue Download go-ipfs on the right side of the page.
  • Open/extract the archive.
  • Move ipfs to your path ( can do it for you).

From Linux package managers

Arch Linux

In Arch Linux go-ipfs is available as go-ipfs package.

$ sudo pacman -S go-ipfs

Development version of go-ipfs is also on AUR under go-ipfs-git. You can install it using your favourite AUR Helper or manually from AUR.


For Linux and MacOSX you can use the purely functional package manager Nix:

$ nix-env -i ipfs

You can also install the Package by using it's attribute name, which is also ipfs.


With snap, in any of the supported Linux distributions:

$ sudo snap install ipfs

Build from Source

Install Go

The build process for ipfs requires Go 1.9 or higher. If you don't have it: Download Go 1.9+.

You'll need to add Go's bin directories to your $PATH environment variable e.g., by adding these lines to your /etc/profile (for a system-wide installation) or $HOME/.profile:

export PATH=$PATH:/usr/local/go/bin
export PATH=$PATH:$GOPATH/bin

(If you run into trouble, see the Go install instructions).

Download and Compile IPFS

$ go get -u -d

$ cd $GOPATH/src/
$ make install

If you are building on FreeBSD instead of make install use gmake install.

Building on less common systems

If your operating system isn't officially supported, but you still want to try building ipfs anyways (it should work fine in most cases), you can do the following instead of make install:

$ make install_unsupported

Note: This process may break if gx (used for dependency management) or any of its dependencies break as go get will always select the latest code for every dependency, often resulting in mismatched APIs.


  • Separate instructions are available for building on Windows.
  • Also, instructions for OpenBSD.
  • git is required in order for go get to fetch all dependencies.
  • Package managers often contain out-of-date golang packages. Ensure that go version reports at least 1.9. See above for how to install go.
  • If you are interested in development, please install the development dependencies as well.
  • WARNING: Older versions of OSX FUSE (for Mac OS X) can cause kernel panics when mounting! We strongly recommend you use the latest version of OSX FUSE. (See
  • For more details on setting up FUSE (so that you can mount the filesystem), see the docs folder.
  • Shell command completion is available in misc/completion/ipfs-completion.bash. Read docs/ to learn how to install it.
  • See the init examples for how to connect IPFS to systemd or whatever init system your distro uses.

Development Dependencies

If you make changes to the protocol buffers, you will need to install the protoc compiler.


Updating using ipfs-update

IPFS has an updating tool that can be accessed through ipfs update. The tool is not installed alongside IPFS in order to keep that logic independent of the main codebase. To install ipfs update, download it here.

Downloading IPFS builds using IPFS

List the available versions of go-ipfs:

$ ipfs cat /ipns/

Then, to view available builds for a version from the previous command ($VERSION):

$ ipfs ls /ipns/$VERSION

To download a given build of a version:

$ ipfs get /ipns/$VERSION/go-ipfs_$VERSION_darwin-386.tar.gz # darwin 32-bit build
$ ipfs get /ipns/$VERSION/go-ipfs_$VERSION_darwin-amd64.tar.gz # darwin 64-bit build
$ ipfs get /ipns/$VERSION/go-ipfs_$VERSION_freebsd-amd64.tar.gz # freebsd 64-bit build
$ ipfs get /ipns/$VERSION/go-ipfs_$VERSION_linux-386.tar.gz # linux 32-bit build
$ ipfs get /ipns/$VERSION/go-ipfs_$VERSION_linux-amd64.tar.gz # linux 64-bit build
$ ipfs get /ipns/$VERSION/go-ipfs_$VERSION_linux-arm.tar.gz # linux arm build
$ ipfs get /ipns/$VERSION/go-ipfs_$ # windows 64-bit build


  ipfs - Global p2p merkle-dag filesystem.

  ipfs [<flags>] <command> [<arg>] ...

    init          Initialize ipfs local configuration
    add <path>    Add a file to ipfs
    cat <ref>     Show ipfs object data
    get <ref>     Download ipfs objects
    ls <ref>      List links from an object
    refs <ref>    List hashes of links from an object

    block         Interact with raw blocks in the datastore
    object        Interact with raw dag nodes
    files         Interact with objects as if they were a unix filesystem

    daemon        Start a long-running daemon process
    mount         Mount an ipfs read-only mountpoint
    resolve       Resolve any type of name
    name          Publish or resolve IPNS names
    dns           Resolve DNS links
    pin           Pin objects to local storage
    repo          Manipulate an IPFS repository

    id            Show info about ipfs peers
    bootstrap     Add or remove bootstrap peers
    swarm         Manage connections to the p2p network
    dht           Query the DHT for values or peers
    ping          Measure the latency of a connection
    diag          Print diagnostics

    config        Manage configuration
    version       Show ipfs version information
    update        Download and apply go-ipfs updates
    commands      List all available commands

  Use 'ipfs <command> --help' to learn more about each command.

  ipfs uses a repository in the local file system. By default, the repo is located
  at ~/.ipfs. To change the repo location, set the $IPFS_PATH environment variable:

    export IPFS_PATH=/path/to/ipfsrepo

Getting Started

See also:

To start using IPFS, you must first initialize IPFS's config files on your system, this is done with ipfs init. See ipfs init --help for information on the optional arguments it takes. After initialization is complete, you can use ipfs mount, ipfs add and any of the other commands to explore!

Some things to try

Basic proof of 'ipfs working' locally:

echo "hello world" > hello
ipfs add hello
# This should output a hash string that looks something like:
# QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o
ipfs cat <that hash>

Docker usage

An IPFS docker image is hosted at To make files visible inside the container you need to mount a host directory with the -v option to docker. Choose a directory that you want to use to import/export files from IPFS. You should also choose a directory to store IPFS files that will persist when you restart the container.

export ipfs_staging=</absolute/path/to/somewhere/>
export ipfs_data=</absolute/path/to/somewhere_else/>

Start a container running ipfs and expose ports 4001, 5001 and 8080:

docker run -d --name ipfs_host -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p -p ipfs/go-ipfs:latest

Watch the ipfs log:

docker logs -f ipfs_host

Wait for ipfs to start. ipfs is running when you see:

Gateway (readonly) server
listening on /ip4/

You can now stop watching the log.

Run ipfs commands:

docker exec ipfs_host ipfs <args...>

For example: connect to peers

docker exec ipfs_host ipfs swarm peers

Add files:

cp -r <something> $ipfs_staging
docker exec ipfs_host ipfs add -r /export/<something>

Stop the running container:

docker stop ipfs_host


If you have previously installed IPFS before and you are running into problems getting a newer version to work, try deleting (or backing up somewhere else) your IPFS config directory (~/.ipfs by default) and rerunning ipfs init. This will reinitialize the config file to its defaults and clear out the local datastore of any bad entries.

Please direct general questions and help requests to our forum or our IRC channel (freenode #ipfs).

If you believe you've found a bug, check the issues list and, if you dont see your problem there, either come talk to us on IRC (freenode #ipfs) or file an issue of your own!


Please see!

This repository falls under the IPFS Code of Conduct.

Want to hack on IPFS?

Want to read our code?

Some places to get you started. (WIP)

Main file: cmd/ipfs/main.go
CLI Commands: core/commands/
Bitswap (the data trading engine): exchange/bitswap/




go-ipfs open issues Ask a question     (View All Issues)
  • almost 3 years add option to disable libp2p bandwidth metrics
  • almost 3 years ipfs object get discrepency in curl vs cli api
  • almost 3 years Can't access /ipfs while /ipns works
  • almost 3 years Preflighted CORS on API is broken
  • almost 3 years Config set fails if there is entry in config that is integer bigger than 1e6
  • almost 3 years HTTP API docs generator as part of go-ipfs
  • almost 3 years Refactor Daemon mode options
  • almost 3 years Config Option For Enabling Filestore?
  • almost 3 years New Behaviour of add command
  • almost 3 years t0400 add-and-cat failure
  • almost 3 years write 'current datastore format' to repo
  • almost 3 years Performance: ipfs add I/O (prefer serving data, be lazy)
  • almost 3 years Performance: ipfs add I/O (rotational disks)
  • almost 3 years HTTP API Add Crashes Daemon
  • almost 3 years Test failure due to gateway hang
  • almost 3 years Improve Garbage Collection Performance
  • almost 3 years Adding files with curl via HTTP API endpoint fails unless HTTP/1.0 is used
  • almost 3 years Can view / request ipfs seeders/leechers ?
  • almost 3 years Reduce number of threads stuck in sync of datastore
  • almost 3 years Stop using gx/gx-go
  • almost 3 years Both go and js clients send "Content-Disposition: file;" when adding files
  • almost 3 years Writeup of router kill issue
  • almost 3 years Reduce idle bandwidth usage
  • almost 3 years Reduce memory usage
  • almost 3 years Investigate Performance characteristics of 10GB LAN Transfer
  • almost 3 years Improve time to add 10,000 files serially.
  • about 3 years Private Networks - First Implementation
  • about 3 years enchancement: Limit outgoing connections to avoid killing routers
  • about 3 years object get hash returns different object
  • about 3 years Invalid peer address
go-ipfs open pull requests (View All Pulls)
  • trying to use port zero for ipfs daemon in sharness tests
  • Remove headers for ยซ ipfs object links ยป.
  • appveyor: disable parallel builds
  • fuse travis-ci
  • Prevents 'ipfs name publish' when /ipns is mounted.
  • Do not install gx if there is already one in system
  • use gx vendored packages instead of godeps ones
  • Enumerate log level subsystem commands
  • Capitalized `Tokens`
  • Capitalized Merkle, added single quotes, periods
  • Normalised Example heading, added dollar sign to examples
  • Add dns and resolve commands to ROAPI
  • Use binary search to get node link
  • repo: add `ipfs repo stat` command
  • Make non recursive resolve print the result
  • Close errnotifier chan on err
  • Use 'dag' forall namespace import prefixes of merkledag
  • ipfs get: set correct content-type on resp
  • Fix LinksSize calculation in node.Stat()
  • allow promises to fail
  • add more events for debugging
  • Restrict ipfs object patch in ro api
  • Reduce the number of process zombies on daemon shutdown
  • bitswap GetBlocks: CancelWant on ctx cancel
  • Change all mfs references to unixfs
  • Detect content charset in gateway serve
  • Remove duplicate Transfer-Encoding header
  • Make gateway POST handle multipart file & pin flag
  • Fixed: On windows 'ipfs add -r .' used the full path
  • More robust version checking
  • update appveyor go version
  • Save gx dependencies into vendor/ folder
  • Makes install from source instructions clearer.
  • assert that you must build from inside your gopath
  • Simplify merkledag package interface to ease IPLD inclusion
  • metrics: rework prometheus integration
  • add utp listeners to default config
  • fix dht command key escaping
  • Change mDNS service string to conform to RFC6763 standard.
  • Use net/url to escape paths in web-ui
  • Out of range in ipfs add
  • install: Improve linux ipfs install script
  • correct import in fuse tests
  • Makes repo existance check more sensitive.
  • Moved verbose option to clear subcommand only
  • Add programatic defaults
  • Added a long description to add
  • remove init -f option, its bad
  • Pin command fixes
  • Edited object patch set-data doc
  • try to raise ulimit if its too low
  • Ipfs 0.4.0 changelog
  • build: include commit hash & version
  • add a ipfs repo ls-roots command
  • Support for listing only cached links in refs command
  • wire contexts into bitswap requests more deeply
  • `tar cat` should return appropriate headers
  • add NetBSD support
  • [WIP] Towards Issue #875, avoid duplicating files added to ipfs
  • basic pubsub commands
  • `ipfs repo version` command
  • add a dist_get script for getting bins from
  • Implements repository initialization with default config
  • Updated bash auto complete
  • Close errnotifier chan on err
  • readme: mention building from source on windows
  • Use gx for iptb
  • [rfc] bash completion improvements
  • Add --repo option to ipfs init.
  • [WIP] Return an error when `object get --encoding=protobuf` fails
  • Correctly set the content type for `object get --encoding=protobuf`
  • Offline daemon mode
  • fix mfs cp/mv bug
  • Add helptext, default logic to `ipfs stats`
  • Set correct content-type for ipfs get
  • Added Default logic to `files` cmd
  • Add Defaults to `ipfs add`
  • add test to enforce helptext on commands
  • [WIP] Towards Issue #875, avoid duplicating files added to ipfs
  • Add check for HEAD response to be empty
  • Fix commands --flags not showing flags via HTTP API
  • update libp2p to v3.2.3
  • Expose corenet API
  • build: include commit hash & version
  • Second wave of gx migrations
  • docker: simplify git ref resolution, thanks @chriscool
  • Make t0030 use iptb for consistent test passing.
  • update protocol IDs to use versioned strings
  • Remove errors pointed out by govet
  • Decapitalized log.Debug messages
  • bitswap: add `ledger` subcommand
  • Change default behaviour of ls not to resolve type of subnodes
  • Change logic of stdin input to be last and only if required
  • [WIP] command: bitswap ledger
  • Updated authors doc
  • Add
  • Add synopsis autogenerator and no- prefix bool options
  • Add CORS headers to Read Only Gateway Default config
  • Added note about error codes
  • docs: decapitalize IPFS where possible
  • test: Run t0080-repo test offline
  • encode keys to datastore with base32 standard encoding
  • [WIP] Implement Basic LRU Cache for merkledag nodes.
  • Add ARC caching and bloom filter for blockstorage
  • Core API and go-ipfs-core-api
  • Expose corenet on the command line
  • dht: add in code to detect and diagnose #3032
  • bitswap: fix a minor data race
  • docs: add branch naming conventions
  • CHANGELOG for 0.4.3-rc2
  • Put all Taglines & most Option descriptions in active, present tense
  • supporting symlinks in web-server
  • Edit issue reporting guides
  • Cleanup makefiles
  • assets: add GPG key
  • mount: ensure a private key is loaded before mounting /IPNS/
  • Alias 'ipfs --version' to 'ipfs version'
  • gateway: degrade error in gateway to log to reduce noise
  • [WIP] Add "ipfs block rm" command.
  • blocks/blockstore: Get ARC cache and context passing
  • Improve the script
  • remove randbo dep, its no longer needed
  • improve test coverage on merkledag package
  • bump go requirement to 1.7
  • update deps for libp2p 3.4.0
  • Updated BASH auto complete
  • cmds: implement ipfs dht provide command
  • bitswap: don't re-provide blocks we've provided very recently
  • test: 80% coverage of unixfs/io [WIP]
  • Add test for 'ipfs config replace'
  • Implement unixfs sharding
  • add test to be run to detect future regressions in pinsets
  • Turn merkledag.Node into an interface
  • add: Allow proper adding of multiple directories with a single add call
  • readme: fix go get invocations
  • Add the packaging metadata to build the ipfs snap
  • RFC: Distinguish between Offline and Local Mode.
  • Adder: Fix multi-file add so it works as expected.
  • WIP: Add support for multiple blockstores
  • gateway: use core api for serving POST requests
  • Revert "Merge pull request #2657 from ipfs/feature/add-defaults-to-add"
  • cmd: validate repo/api file and print nicer error message
  • Initial Core API, and gateway integration
  • Fix whitespace discrepency in security-notes
  • Expose corenet interface
  • add: [Windows] Drive root parse fix
  • Implement cbor ipld nodes and a first pass at the 'dag' command
  • allow cid format selection in block put command
  • WIP: Add FullName option to adder.
  • WIP: Basic Filestore implementation.
  • builder: add blockstoreOption for customizing the blockstore
  • Fix/mfs/cleanup
  • Update go-libp2p across codebase
  • Fix panic in dagreader with raw nodes
  • use floodsub version 0.8.1
  • (WIP) Feat/floodsub-unsubscribe
  • Private network implementation
  • Roadmap generator and Generated Q4 Roadmap
  • configuration for labels-and-milestones sync tool
  • WIP: Use NextSync method in Datastore
  • add option to enable go-multiplex experiment
  • bitswap: add a deadline to sendmsg calls
  • merkledag: retain cid types when roundtripping through a ProtoNode
  • bitswap: clean up ledgers when disconnecting
  • add sharness test for pubsub
  • Gxify fuse lib, update it, might fix OSX with new fuzz and move lots of stuff to gx
  • fuse: Parse OSX fuse version properly
  • BugFix IsHidden (FullPath for GetFileAttributes)
  • docker: expose port for /tcp/ws transport
  • Fix link in `ipfs stats bw` help message
  • Tests for mfsr.go
  • Remove 'FindProviders` from routing mocks
  • Add multiple performance metrics
  • Command name resolve: add -k flag, fix #3567
  • Add closed PRs, Issues throughput
  • Make pin rm not try to find pinned ancestors by default
  • Pass cids instead of nodes around in EnumerateChildrenAsync
  • quickstart images are unreachable
  • update to fixed cbor ipld lib
  • `make source` for installation in unsupported systems
  • more configurable datastore configs
  • docker: More convenient access to ipfs commands
  • add fetch flag to pin add and Pin() functions
  • Added /name/upload command definition
  • Swarm discovery on the gateway (readonly) interface
  • keystore: Property based testing
  • bootstrap: add a few /ip6 nodes
  • Implemented experimental corenet application protocol support.
  • RFC: Handle Symbolic links in the Gateway
  • Makefile rework and sharness test coverage
  • Core API refinements and efficiency improvements
  • WIP Fix DagModifier for raw-leaves nodes
  • improved gateway directory listing for sharded nodes
  • Fix typo in message when file is not determined
  • Implement ipfs key {rm, rename}
  • Implement ipfs shutdown command
  • WIP: add PeerID lookup
  • Bitswap sessions
  • Extract and rework commands package
  • Add FOSSA badge/reports
  • implement ipfs pin update
  • WIP "pin verify".
  • filestore rm
  • Safe check rlimit syscall and refactoring
  • sharness: add /ws multinode test
  • Add support for s3 backed ipfs repo
  • routing: Implement GetValuesAsync
  • Link caching
  • Implemented experimental corenet interface
  • Remove duplicate release checklist
  • Fix the PUT-existing bug in writable gateway API
  • Allow the use of the Range header in WebTorrent
  • Corrected GOPATH and GOBIN path example
  • Add & update packages
  • mega update
  • Update ipns validator
  • Add a 'ipfs files tree' command
  • gateway: expose commands for js-libp2p delegated routing
  • Avoid closing channels in commands if the context has errored (e.g timed out).
  • Make repo gc call CollectGarbage on datastore
  • coreapi: Pin API
  • Added sharding to experimental features
  • commands/block: use CIDv1 with custom mhtype
  • update link to filestore experimental status
  • Feat: ipfs repo size command
  • coreapi: Block API
  • [RFC] don't sniff the filename to determine the content type
  • Implement the command "ipfs repo has"
  • sharness: Generate JUnit test reports
  • [WIP] MFS improvements
  • Add Opentracing plugin support
  • IPRS Proof of Concept
  • coreapi: Basic object API implementation
  • Document global options (-r, --enc and --timeout)
  • RFC: Better Error Messages
  • core: get cmd outPath removes trailing slash from args - fixes #3729
  • Add Event Logging to Add Command
  • [WIP] Implement ipfs name follow
  • Implement "repo rm-root" command to unlink the files API root.
  • Use ResolveUnixfsOnce as default resolver.
  • don't warn when trying to send wantlist to disconnected peers
  • Create Jenkinsfile
  • Adding tests and documentation for package path.
  • Refactoring towards gateway extraction
  • Validate size in the DagReaders
  • build: match Go's GOPATH defaults behaviour
  • Doc: golint-ify routing module
  • [RFC] Improve paths in CoreApi
  • shutdown notifications engine when closing a bitswap session
  • blockservice: add BlockedFetched/Added/Removed events
  • Fix mulitaddr typo
  • commands: switch object to CoreAPI
  • merge github-issue-guide with the issue template
  • refactor: extract fs lock into go-fs-lock
  • [WIP] Add Filestore support for the trickle DAG builder
  • Add options for record count and timeout for resolving DHT paths
  • make init command use go-ipfs-cmds
  • Refactor trickle DAG builder
  • fix race in TestWantlistClearsOnCancel
  • make files stat --with-local return immediately when no data is present
  • Disable sorting on unmarshalled blocks and json.
  • reduce bitswap lock contention
  • Feat: remove circular dependencies in merkledag package tests
  • Create a raw node instead of a file node when there is no content.
  • Change Windows build documentation
  • bitswap: reduce level when logging about disconnected peers to info
  • Fix get output path
  • coreapi: Refactor options
  • Stateful plugin loading
  • coreapi: PubSub API
  • coreapi: DHT API
  • coreapi: Swarm API
  • coreapi: Split the interface into multiple files
  • Add boolean value to type assertion, for skipping assertion panic
  • Update DagModifier.expandSparse() to assign new ipld.Node to the curNode field
  • Update broken links
  • misc: add confirmation to archive-branches script
  • fix incorrect Read calls
  • commands: resolve: resolve key names
  • commands: publish: check if key matches node ID
  • [WIP] Make the Node methods on ProtoNode thread-safe
  • redundant word
  • convert the dht commands to the new commands lib
  • dag: diff: check CIDs in base case when comparing nodes
  • migrate repo verify to new cmds library.
  • [WIP] MFS improvements
  • [WIP] Named pins & pins stored in datastore
  • add: hash-only: set the prefix for MFS root
  • Move namesys republisher records into their own place in the datastore
  • unixfs: clean path in DagArchive
  • Update to latest go-datastore. Remove thirdparty/datastore2
go-ipfs list of languages used
Other projects in Go