Skip to main content

Python IPFS HTTP CLIENT library

Project description


standard-readme compliant Build Status

Python IPFS HTTP Client Library

Check out the HTTP Client reference for the full command reference.

Important: The ipfsapi PIP package and Python module have both been renamed to ipfshttpclient! See the relevant section of the README for details.

Note: This library constantly has to change to stay compatible with the IPFS HTTP API. Currently, this library is tested against go-ipfs v0.4.19. You may experience compatibility issues when attempting to use it with other versions of go-ipfs.

The following versions have been expliciently backlisted for know compatiblity problems:

  • 0.4.20

Table of Contents


Install with pip:

pip install ipfshttpclient


Basic use-case (requires a running instance of IPFS daemon):

>>> import ipfshttpclient
>>> client = ipfshttpclient.connect('', 5001)
>>> res = client.add('test.txt')
>>> res
{'Hash': 'QmWxS5aNTFEc9XbMX1ASvLET1zrqEaTssqt33rVZQCQb22', 'Name': 'test.txt'}

For real-world scripts you can reuse TCP connections using a context manager or manually closing the session after use:

import ipfshttpclient

# Share TCP connections using a context manager
with ipfshttpclient.connect() as client:
	hash = client.add('test.txt')['Hash']

# Share TCP connections until the client session is closed
class SomeObject:
	def __init__(self):
		self._client = ipfshttpclient.connect(session=True)

	def do_something(self):
		hash = self._client.add('test.txt')['Hash']

	def close(self):  # Call this when your done

Administrative functions:

{'Addresses': ['/ip4/',
 'AgentVersion': 'go-ipfs/0.4.10',
 'ID': 'QmS2C4MjZsv2iP1UDMMLCYqJ4WeJw8n3vXx1VKxW1UbqHS',
 'ProtocolVersion': 'ipfs/0.1.0',
 'PublicKey': 'CAASpgIwgg ... 3FcjAgMBAAE='}

Pass in API options:

>>> client.pin_ls(type='all')
{'Keys': {'QmNMELyizsfFdNZW3yKTi1SE2pErifwDTXx6vvQBfwcJbU': {'Count': 1,
                                                             'Type': 'indirect'},
          'QmNQ1h6o1xJARvYzwmySPsuv9L5XfzS4WTvJSTAWwYRSd8': {'Count': 1,
                                                             'Type': 'indirect'},

Add a directory and match against a filename pattern:

>>> client.add('photos', pattern='*.jpg')
[{'Hash': 'QmcqBstfu5AWpXUqbucwimmWdJbu89qqYmE3WXVktvaXhX',
  'Name': 'photos/photo1.jpg'},
 {'Hash': 'QmSbmgg7kYwkSNzGLvWELnw1KthvTAMszN5TNg3XQ799Fu',
  'Name': 'photos/photo2.jpg'},
 {'Hash': 'Qma6K85PJ8dN3qWjxgsDNaMjWjTNy8ygUWXH2kfoq9bVxH',
  'Name': 'photos/photo3.jpg'}]

Or add a directory recursively:

>>> client.add('fake_dir', recursive=True)
[{'Hash': 'QmQcCtMgLVwvMQGu6mvsRYLjwqrZJcYtH4mboM9urWW9vX',
  'Name': 'fake_dir/fsdfgh'},
 {'Hash': 'QmNuvmuFeeWWpxjCQwLkHshr8iqhGLWXFzSGzafBeawTTZ',
  'Name': 'fake_dir/test2/llllg'},
 {'Hash': 'QmX1dd5DtkgoiYRKaPQPTCtXArUu4jEZ62rJBUcd5WhxAZ',
  'Name': 'fake_dir/test2'},
 {'Hash': 'Qmenzb5J4fR9c69BbpbBhPTSp2Snjthu2hKPWGPPJUHb9M',
  'Name': 'fake_dir'}]

This module also contains some helper functions for adding strings and JSON to IPFS:

>>> lst = [1, 77, 'lol']
>>> client.add_json(lst)
>>> client.get_json(_)
[1, 77, 'lol']


Documentation (currently mostly API documentation unfortunately) is available on IPFS:

The ipfs command-line Client documentation may also be useful in some cases.

Important changes from ipfsapi 0.4.x

  • Tons of methods has been renamed, ensure that you code runs without warnings with the last version of ipfsapi before attempting to upgrade!
  • The Python package has been renamed from ipfsapi to ipfshttpclient
  • The PIP module has been renamed from ipfsapi to ipfshttpclient (please update your requirement files)
  • The client.*_pyobj family of functions has been dropped due to security concerns
  • The client.bitswap.unwant method has been dropped – it's endpoint has been removed by go-ipfs
  • The client.files.file_ls method has been dropped – deprecated for a long time, use instead
  • Passing a list of parameters to client.add will now fail, just pass several individual parameters instead
  • Some functions that may also return multiple items, will now also return a list when returning only a single item (don't worry about it unless it actually breaks for you)
  • The API deamon location is now described using MultiAddr, hence rather then doing ipfshttpclient.connect(host, port) to pass the network address parameters, use:
    • ipfshttpclient.connect("/dns/<host>/tcp/<port>/http") (for hostnames such as localhost)
    • ipfshttpclient.connect("/ip4/<IP-address>/tcp/<port>/http") (for IPv4 addresses)
    • ipfshttpclient.connect("/ip6/<IP-address>/tcp/<port>/http") (for IPv6 addresses)
    • Use …/https rather then …/http to connect to the API deamon using HTTPS
  • The client now supports keeping session contexts around between API calls, you probably should make use of this facility in your code

Thank you @AlibabasMerchant, @lordcirth and @radfish (in order of subjective contributions) for helping making this happen!

Featured Projects

Projects that currently use py-ipfs-http-client. If your project isn't here, feel free to submit a PR to add it!



Join us on IRC at #ipfs on if you have any suggestions or questions, or if you just want to discuss IPFS and python.

Bug reports

You can submit bug reports using the GitHub issue tracker.

Pull requests

Pull requests are welcome. Before submitting a new pull request, please make sure that your code passes both the code formatting check:

$ tox -e codestyle

And the unit tests:

$ tox

You can arrange to run the code style tests automatically before each commit by installing a pre-commit hook:

$ ./tools/pre-commit --install

Please make sure to include new unit tests for new features or changes in behavior. We aim to bring coverage to 100% at some point.


This code is distributed under the terms of the MIT license. Details can be found in the file LICENSE in this repository.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for ipfshttpclient, version 0.4.12
Filename, size File type Python version Upload date Hashes
Filename, size ipfshttpclient-0.4.12-py2.py3-none-any.whl (157.9 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size ipfshttpclient-0.4.12.tar.gz (80.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page