Python IPFS HTTP Client Library

0.7.0 · active · verified Thu Apr 16

The ipfshttpclient library provides a client interface to the IPFS HTTP API, allowing Python applications to interact with an IPFS daemon. This library version `0.7.0`, released in March 2021, is tested against go-ipfs v0.7.0 and strives to support the last 5 releases of go-IPFS. It was previously known as `ipfsapi`.

Common errors

```
ModuleNotFoundError: No module named 'ipfsapi'
```
cause Attempting to import the old `ipfsapi` package/module name after installing `ipfshttpclient` or if `ipfsapi` was never installed.

fix Change `import ipfsapi` to `import ipfshttpclient`. If you explicitly need the old `ipfsapi` shim, install it via `pip install ipfsapi`, but it's recommended to migrate to `ipfshttpclient`.
```
ipfshttpclient.exceptions.VersionMismatch: Unsupported daemon version '0.X.Y' (not in range: A.B.C ≤ … < D.E.F)
```
cause The version of your `ipfshttpclient` library is incompatible with the version of the `go-ipfs` daemon it's trying to connect to. The daemon version is outside the client's supported range.

fix Update your `ipfshttpclient` library to a version compatible with your `go-ipfs` daemon (or vice-versa). Check the `ipfshttpclient` GitHub page for current compatibility. For `ipfshttpclient` 0.7.0, it supports `go-ipfs` 0.4.23 to approximately 0.8.0.
```
ipfshttpclient.exceptions.ConnectionError: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused'))
```
cause The `ipfshttpclient` library could not connect to the specified IPFS daemon. This typically means no IPFS daemon is running, it's running on a different address/port, or a firewall is blocking the connection.

fix Verify that your IPFS daemon is running (run `ipfs daemon` in a separate terminal) and that `ipfshttpclient.connect()` is configured to connect to the correct address and port (default is `/dns/localhost/tcp/5001/http`). Check firewall settings if connecting to a remote daemon.
```
TypeError: 'list' object is not callable (e.g., `client.add(['file1', 'file2'])` fails)
```
cause In `ipfshttpclient` 0.7.0, the `add` method expects a single file path or a file-like object, not a list of paths for batch adding. While IPFS can handle multiple files, the `add` API for the Python client typically processes one file/directory at a time or requires iterating.

fix Iterate over your list of files and call `client.add()` for each file. For adding directories, pass the directory path directly to `client.add()` with `recursive=True`.

Warnings

breaking The package and module name changed from `ipfsapi` to `ipfshttpclient`. The `ipfsapi` PyPI package is now a deprecated, unmaintained wrapper. Direct usage of `ipfsapi` should be migrated.
Fix: Update your `pip install` command to `pip install ipfshttpclient` and change all `import ipfsapi` statements to `import ipfshttpclient`.
breaking The `ipfshttpclient` library requires compatibility with the IPFS HTTP API of the daemon it connects to. Using an older `ipfshttpclient` version with a much newer `go-ipfs` daemon (or vice-versa) can lead to `VersionMismatch` exceptions or unexpected behavior.
Fix: Consult the `ipfshttpclient` documentation or GitHub README for supported `go-ipfs` daemon versions for your `ipfshttpclient` version. Upgrade `ipfshttpclient` or downgrade `go-ipfs` as necessary. For `ipfshttpclient` 0.7.0, it's generally compatible with `go-ipfs` v0.4.23 up to v0.7.0/0.8.0.
gotcha There is an entirely separate, *unmaintained* library called `ipfsApi` (with a capital 'A') which does not work with recent `go-IPFS` versions. Do not confuse it with `ipfsapi` (lowercase, the deprecated predecessor to `ipfshttpclient`).
Fix: Always use `ipfshttpclient`. Double-check import statements and `pip install` commands to ensure you are not installing or importing the defunct `ipfsApi` library.
gotcha Connecting `ipfshttpclient.connect()` to a public IPFS gateway (e.g., `/dns/ipfs.io/tcp/443/https`) provides extremely limited read-only access and will likely fail for write operations like `add` or `pin`. Full functionality requires connecting to a local, running IPFS daemon.
Fix: Ensure an IPFS daemon is running locally (e.g., by executing `ipfs daemon` in your terminal) and connect to its API address, usually `http://127.0.0.1:5001` or `/dns/localhost/tcp/5001/http`.

Install

pip install ipfshttpclient Install stable release

Imports

ipfshttpclient
wrong:
```
import ipfsapi
```
correct:
```
import ipfshttpclient
```
The package and module were renamed from 'ipfsapi' to 'ipfshttpclient'. 'ipfsapi' is now an unmaintained wrapper.
connect
```
client = ipfshttpclient.connect()
```
Used to establish a connection to a running IPFS daemon.

Quickstart

This quickstart demonstrates how to connect to a local IPFS daemon, add a file, and retrieve its content by hash. Ensure you have an IPFS daemon running in the background before executing.

import ipfshttpclient
import os

# Ensure an IPFS daemon is running (e.g., `ipfs daemon` in your terminal)
# Connect to the local IPFS daemon (default: /dns/localhost/tcp/5001/http)
try:
    client = ipfshttpclient.connect()
    print("Successfully connected to IPFS daemon.")
    
    # Example: Add a simple text file
    file_content = "Hello, IPFS!\n"
    file_name = "test.txt"
    with open(file_name, 'w') as f:
        f.write(file_content)
    
    res = client.add(file_name)
    print(f"Added '{file_name}': {res}")
    
    # Example: Cat (retrieve content) by hash
    retrieved_content = client.cat(res['Hash']).decode('utf-8')
    print(f"Retrieved content for {res['Hash']}:\n{retrieved_content}")
    
    os.remove(file_name)
    
except ipfshttpclient.exceptions.ConnectionError as e:
    print(f"Error connecting to IPFS daemon: {e}")
    print("Please ensure your IPFS daemon is running and accessible (e.g., 'ipfs daemon' in a separate terminal).")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →