Skip to main content

IPFS API Bindings for Python

Project description

image0 image1 image2 standard-readme compliant image4 Build Status

A python client library for the IPFS API

A python client library for the IPFS API

Check out the client API reference for the full command reference.

Important: The py-ipfs-api PIP package and Python module have both been renamed to ipfsapi (no dash, lower-case a).
The legacy ipfs-api/ipfsApi package/module will only work for IPFS 0.3.x and Python 2 and is deprecated. Please upgrade!

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.10. You may experience compatibility issues when attempting to use it with other versions of go-ipfs.


Install with pip:

pip install ipfsapi


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

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

Administrative functions:

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

Pass in API options:

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

Add a directory and match against a filename pattern:

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

Or add a directory recursively:

>>> api.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.2.x

  • The Python package has been renamed from ipfsApi to ipfsapi
  • The PIP module has been renamed from ipfs-api to ipfsapi (please update your requirement files)
  • A lot of changes in the internal code
    • Commands have been completely removed
    • Usage of requests or other libraries is considered an implementation detail from now on
  • Most parts of the library (except for Client()) are now considered internal and may therefore break at any time (reference)
    • We will try to keep breakage for these modules at a minimum
    • If you require stabilisation of some feature please open an issue with the feature in question and your preceived use-case
  • Raised exceptions have been completely changed and are now documented with guaranteed backwards compatibility (reference)
  • The new ipfsapi.connect() function allows creating a Client instance, while also checking whether a compatible IPFS daemon instance is actually available
  • Methods in Client() now have parameters for options



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 pep8 formatting check:

$ tox -e pep8

And the unit tests:

$ tox

You can arrange to run the pep8 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.


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

Project details

Release history Release notifications

This version
History Node


History Node


History Node


History Node


Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
ipfsapi-0.4.2.post1-py2.py3-none-any.whl (41.3 kB) Copy SHA256 hash SHA256 Wheel 3.6 Aug 9, 2017
ipfsapi-0.4.2.post1.tar.gz (38.5 kB) Copy SHA256 hash SHA256 Source None Aug 9, 2017

Supported by

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