The Python SDK provides access from Python to the Arvados API and Keep. It also includes a number of command line tools for using and administering Arvados and Keep, and some conveniences for use in Crunch scripts; see Crunch utility libraries for details.


If you are logged in to an Arvados VM, the Python SDK should be installed.

To use the Python SDK elsewhere, you can install from a distribution package, PyPI, or source.


The Python SDK requires Python 2.7.

Option 1: Install from distribution packages

First, add the appropriate package repository for your distribution.


On CentOS 6 and RHEL 6, these packages require a more recent version of Python from Software Collections. The Software Collection will be installed automatically as long as Software Collections are enabled on your system.

To enable Software Collections on CentOS, run:

~$ sudo yum install centos-release-scl scl-utils

To enable Software Collections on RHEL, follow section 2.1 of Red Hat’s Installation chapter.

On Red Hat-based systems:

~$ sudo yum install python-arvados-python-client

On Debian-based systems:

~$ sudo apt-get install python-arvados-python-client

Option 2: Install with pip

Run pip-2.7 install arvados-python-client in an appropriate installation environment, such as a virtualenv.

If your version of pip is 1.4 or newer, the pip install command might give an error: “Could not find a version that satisfies the requirement arvados-python-client”. If this happens, try pip-2.7 install --pre arvados-python-client.

Option 3: Install from source

Install the python-setuptools package from your distribution. Then run the following:

~$ git clone
~$ cd arvados/sdk/python
~/arvados/sdk/python$ python2.7 install

You may optionally run the final installation command in a virtualenv, or with the --user option.

Test installation

If the SDK is installed and your ARVADOS_API_HOST and ARVADOS_API_TOKEN environment variables are set up correctly (see api-tokens for details), import arvados should produce no errors:

~$ python2.7
Python 2.7.4 (default, Sep 26 2013, 03:20:26)
[GCC 4.7.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import arvados
>>> arvados.api('v1')
<apiclient.discovery.Resource object at 0x233bb50>


Get the User object for the current user:

current_user = arvados.api('v1').users().current().execute()

Get the UUID of an object that was retrieved using the SDK:

my_uuid = current_user['uuid']

Retrieve an object by ID:

some_user = arvados.api('v1').users().get(uuid=my_uuid).execute()

Create an object:

test_link = arvados.api('v1').links().create(

Update an object:


Get a list of objects:

repos = arvados.api('v1').repositories().list().execute()


The general form of an API call is:

arvados.api(api_version).plural_resource_type().api_method(parameter=value, ...).execute()

Many API methods accept a parameter whose name is the same as the resource type. For example, links.create accepts a parameter called link. This parameter should be given as body.


One way to make API calls slightly less verbose is:

arv = arvados.api('v1')
j =

The SDK retrieves the list of API methods from the server at run time. Therefore, the set of available methods is determined by the server version rather than the SDK version.

Previous: SDK Reference Next: Examples

The content of this documentation is licensed under the Creative Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the Apache License, Version 2.0.