java-ipfs-http-client: a Java binding for the IPFS HTTP API

A binding, not an embedded node

java-ipfs-http-client is a Java implementation of the IPFS HTTP API, and the single sentence is the whole architecture.

IPFS is a content addressed distributed filesystem, and the way you talk to it is over an HTTP API exposed by a node. This library is the Java side of that API. It does not contain a node, it does not implement the protocol, and it does not run a daemon. It is a set of Java methods that make HTTP requests to a daemon that is running somewhere else.

The README is a little loose about naming, referring to the project both as java-ipfs-http-client and, in a couple of places, as java-ipfs-api, but the repository and the artifact are java-ipfs-http-client, and the links point at the releases of that project.

The project carries the badges of the wider IPFS ecosystem: made by Protocol Labs, an IPFS project, and a freenode channel badge for the `#ipfs` community chat. It is also standard-readme compliant, which is a specification for the structure of a README and which tells you the README is generated and maintained to a common shape rather than written ad hoc.

That broader ecosystem matters for how you read the project. This is infrastructure software in the sense that it is a dependency of something else, it is versioned and tagged for a package manager to consume, and the licence is MIT with the licence file at the root of the repository.

The releases are 1.5.1 and 1.5.0, both from 2026-01-27, and before that v1.4.4 from 2023-04-06. The last push was on 2026-05-18, the default branch is master, and the project is not archived.

Creating the client and running commands on it

The usage section is short and the API shape is easy to read, which is a good sign for a binding.

You create an IPFS instance with:

IPFS ipfs = new IPFS("/ip4/127.0.0.1/tcp/5001");

That constructor argument is a multiaddr, which is the standard way to address a peer in the IPFS stack. Here it is the loopback address and the API port, so the instance is pointed at a daemon on the same machine.

Then you run commands like:

ipfs.refs.local();

That reads as though the object is a namespace of the API's commands, which is what it is. The HTTP API is a set of RPC endpoints, and the Java class exposes each of them as a method.

Adding a file looks like this:

NamedStreamable.FileWrapper file = new NamedStreamable.FileWrapper(new File("hello.txt"));
MerkleNode addResult = ipfs.add(file).get(0);

The comment on that call explains the shape of the return, that the add method returns a list of merklenodes, in this case there is only one element. A single file produces a single Merkle node, and the code takes the first one. For a directory the list would be longer, one node per file plus the root, which is why the API returns a list rather than a single value and why the example indexes it.

To add a byte array the wrapper type changes:

NamedStreamable.ByteArrayWrapper file = new NamedStreamable.ByteArrayWrapper("hello.txt", "G'day world! IPFS rocks!".getBytes());
MerkleNode addResult = ipfs.add(file).get(0);

The name of the wrapper class carries the payload, and both wrappers implement the same `NamedStreamable` abstraction, which is why the `add` call is identical in the two cases. That is the kind of detail that tells you the API was designed around a common interface rather than around two separate methods.

Reading a file back is the mirror image:

Multihash filePointer = Multihash.fromBase58("QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB");
byte[] fileContents = ipfs.cat(filePointer);

The identifier here is a `Multihash` parsed from Base58, which is the traditional textual form of an IPFS content identifier, and `cat` is the API's name for retrieving a file's contents. More example usage is said to be in the demo directory in the source tree.

The four multiformats dependencies and why they are separate

The dependencies section is short, and the four libraries in it are the reason a Java IPFS client is not a trivial thing to write.

Current versions are listed in the pom.xml, and the corresponding source repositories are multibase, multiaddr, multihash and cid, all under the multiformats and ipld organisations on GitHub.

Each of those handles a different part of the addressing scheme, and separating them is the point. A multihash is the hash function and length that identify content. A multibase is the encoding prefix that says how the rest of the identifier is written, which is what lets the same hash appear as Base58, as hexadecimal or in some other textual form. A multiaddr is a network address format, which is what the constructor argument in the usage example is. A CID, a content identifier, is the modern scheme that combines a multihash with a codec and a version, which is how the ecosystem moved from bare hashes to self-describing identifiers.

So the API in this library takes `Multihash` where a classic IPFS identifier is expected and `String` in multiaddr form where a network address is expected, and both are typed values from the multiformats libraries rather than bare strings. A binding that used plain strings would be simpler to read and would leave every caller to know the encoding rules.

The runtime requirement is Java 11 or newer, while the build requirement is Java 21 with Maven 3.9.6 or newer. That gap is normal and worth knowing about: the library compiles against a newer JDK but produces a jar that runs on older ones, so a team on Java 11 can consume it even though the maintainers build on 21.

The dependencies are described as appropriate versions of other dependencies being included in `dist/lib/`, which is the manual distribution path rather than the package manager one.

Building, testing and the daemon you need

The build section is where the practical requirements live, and there is a distinction between building the library and running its tests that catches people out.

Build time requires Java 21 and Maven 3.9.6 or newer, with the latest patch release recommended. The repository ships a Maven wrapper, so the commands are `./mvnw install` to build and `./mvnw test` to run the tests, and the documentation notes that the install invocation runs them as well.

Then there is the testing requirement, and it is the important one. To run tests, an IPFS daemon must be running on the `127.0.0.1` interface, with `--enable-pubsub-experiment`.

That is a real constraint on the test suite. These are not unit tests against mocked HTTP responses; they run against an actual node. The consequence is that a contributor cannot run the suite without first having a working IPFS installation, and that a CI system needs one too.

Two ways of getting one are documented. The first is the command line, downloading ipfs from the distribution site and running it with `ipfs daemon --enable-pubsub-experiment`. The second is Docker Compose, by running `docker-compose up` from the project root, with the compose file itself showing the shape of it:

services:
  ipfs-daemon:
    image: ipfs/kubo:${KUBO_TAG-release} # default is latest release, see https://github.com/ipfs/kubo#docker
    environment:
      IPFS_TELEMETRY: off
    ports:
      - "4001:4001"
      - "5001:5001"
    user: "ipfs"
    command: [ "daemon", "--enable-pubsub-experiment", "--enable-namesys-pubsub", "--routing=dhtclient" ]

The image is `ipfs/kubo` with the tag taken from an environment variable, so you can pin the node version rather than tracking the latest release. Telemetry is switched off explicitly. Ports 4001 and 5001 are exposed, which are the swarm and API ports respectively, and the process runs as the `ipfs` user rather than root.

The daemon command is the same one the manual instructions use, with two additions: `--enable-namesys-pubsub` for the namesys pubsub mode and `--routing=dhtclient` to use the DHT client for routing. The pubsub experiment flag is the one the test instructions name, and it is a good clue about what the test suite exercises, since pubsub is a streaming subscription API rather than a simple request and response.

There are also two helper scripts at the repository root, `install-run-ipfs.sh` and `mac-install-run-ipfs.sh`, and a `print_test_errors.sh`, which is the kind of script that exists because the test output is long and hard to read.

Getting the artifact, and the versioning rule JitPack imposes

There are two ways to get this library into a Java project, and the package manager route has a rule attached to it that is worth reading before you pin a version.

The first is official releases, where you include `ipfs.jar` from one of the releases along with the dependencies. That is the manual route and it means managing the dependency jars yourself.

The second is Maven, Gradle, SBT or anything else JitPack supports, since package managers are supported through JitPack. For Maven, the pom.xml needs a repository entry and a dependency:

  <repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
  </repositories>

  <dependencies>
    <dependency>
      <groupId>com.github.ipfs</groupId>
      <artifactId>java-ipfs-http-client</artifactId>
      <version>$LATEST_VERSION</version>
    </dependency>
  </dependencies>

The group id is `com.github.ipfs`, which is the JitPack convention of deriving the coordinates from the GitHub organisation, and that is why the repository entry is mandatory: Maven will not look on JitPack without being told to.

The releasing section explains the rule behind it. The version number is specified in pom.xml and must be changed in order to be accurately reflected in the JAR file manifest, and a git tag must be added in the format `vx.x.x` for JitPack to work.

That is a meaningful operational detail for a consumer. JitPack builds an artifact on demand from a tagged commit, so a version you can depend on exists only if the tag exists and matches. It also explains the slightly odd version strings in the release list, where 1.5.0 and 1.5.1 have no `v` prefix while the earlier v1.4.4 does, since the format of the tag is what JitPack reads.

The repository also has a `jitpack.yml` file, which is where the JitPack build configuration lives, and a `.mvn/` directory for the Maven wrapper's configuration.

Editorial conclusion

Adopt java-ipfs-http-client if you have an existing Java service that needs to read from or write to an IPFS node, since the API is direct and the artifact is a normal Maven dependency. Do not adopt it if you need an embedded node, because this is a client for a daemon you run separately and the tests need one on 127.0.0.1, and check first that you can accept the daemon being a required runtime dependency of your deployment, since the library makes no attempt to embed or start one.

Frequently asked questions

Official sources

1. ipfs-shipyard/java-ipfs-http-client on GitHub
2. Issues
3. License: MIT
4. README
5. Releases