{"id":7311,"library":"ipfshttpclient","title":"Python IPFS HTTP Client Library","description":"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`.","status":"active","version":"0.7.0","language":"en","source_language":"en","source_url":"https://github.com/ipfs-shipyard/py-ipfs-http-client","tags":["ipfs","decentralized","p2p","http client","blockchain"],"install":[{"cmd":"pip install ipfshttpclient","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"note":"The package and module were renamed from 'ipfsapi' to 'ipfshttpclient'. 'ipfsapi' is now an unmaintained wrapper.","wrong":"import ipfsapi","symbol":"ipfshttpclient","correct":"import ipfshttpclient"},{"note":"Used to establish a connection to a running IPFS daemon.","symbol":"connect","correct":"client = ipfshttpclient.connect()"}],"quickstart":{"code":"import ipfshttpclient\nimport os\n\n# Ensure an IPFS daemon is running (e.g., `ipfs daemon` in your terminal)\n# Connect to the local IPFS daemon (default: /dns/localhost/tcp/5001/http)\ntry:\n    client = ipfshttpclient.connect()\n    print(\"Successfully connected to IPFS daemon.\")\n    \n    # Example: Add a simple text file\n    file_content = \"Hello, IPFS!\\n\"\n    file_name = \"test.txt\"\n    with open(file_name, 'w') as f:\n        f.write(file_content)\n    \n    res = client.add(file_name)\n    print(f\"Added '{file_name}': {res}\")\n    \n    # Example: Cat (retrieve content) by hash\n    retrieved_content = client.cat(res['Hash']).decode('utf-8')\n    print(f\"Retrieved content for {res['Hash']}:\\n{retrieved_content}\")\n    \n    os.remove(file_name)\n    \nexcept ipfshttpclient.exceptions.ConnectionError as e:\n    print(f\"Error connecting to IPFS daemon: {e}\")\n    print(\"Please ensure your IPFS daemon is running and accessible (e.g., 'ipfs daemon' in a separate terminal).\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Update your `pip install` command to `pip install ipfshttpclient` and change all `import ipfsapi` statements to `import ipfshttpclient`.","message":"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.","severity":"breaking","affected_versions":"< 0.6.0 (for direct 'ipfsapi' usage)"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, especially with go-ipfs >= 0.8.0"},{"fix":"Always use `ipfshttpclient`. Double-check import statements and `pip install` commands to ensure you are not installing or importing the defunct `ipfsApi` library.","message":"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`).","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"Attempting to import the old `ipfsapi` package/module name after installing `ipfshttpclient` or if `ipfsapi` was never installed.","error":"ModuleNotFoundError: No module named 'ipfsapi'"},{"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.","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.","error":"ipfshttpclient.exceptions.VersionMismatch: Unsupported daemon version '0.X.Y' (not in range: A.B.C ≤ … < D.E.F)"},{"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.","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.","error":"ipfshttpclient.exceptions.ConnectionError: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused'))"},{"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`.","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.","error":"TypeError: 'list' object is not callable (e.g., `client.add(['file1', 'file2'])` fails)"}]}