Docker SDK for Python
=====================

|Build Status|

A Python library for the Docker Engine API. It lets you do anything the
``docker`` command does, but from within Python apps – run containers,
manage containers, manage Swarms, etc.

Installation
------------

The latest stable version `is available on
PyPI <https://pypi.python.org/pypi/docker/>`__. Either add ``docker`` to
your ``requirements.txt`` file or install with pip:

::

    pip install docker

If you are intending to connect to a docker host via TLS, add
``docker[tls]`` to your requirements instead, or install with pip:

::

    pip install docker[tls]

Usage
-----

Connect to Docker using the default socket or the configuration in your
environment:

.. code:: python

    import docker
    client = docker.from_env()

You can run containers:

.. code:: python

    >>> client.containers.run("ubuntu:latest", "echo hello world")
    'hello world\n'

You can run containers in the background:

.. code:: python

    >>> client.containers.run("bfirsh/reticulate-splines", detach=True)
    <Container '45e6d2de7c54'>

You can manage containers:

.. code:: python

    >>> client.containers.list()
    [<Container '45e6d2de7c54'>, <Container 'db18e4f20eaa'>, ...]

    >>> container = client.containers.get('45e6d2de7c54')

    >>> container.attrs['Config']['Image']
    "bfirsh/reticulate-splines"

    >>> container.logs()
    "Reticulating spline 1...\n"

    >>> container.stop()

You can stream logs:

.. code:: python

    >>> for line in container.logs(stream=True):
    ...   print line.strip()
    Reticulating spline 2...
    Reticulating spline 3...
    ...

You can manage images:

.. code:: python

    >>> client.images.pull('nginx')
    <Image 'nginx'>

    >>> client.images.list()
    [<Image 'ubuntu'>, <Image 'nginx'>, ...]

`Read the full documentation <https://docker-py.readthedocs.io>`__ to
see everything you can do.

.. |Build Status| image:: https://travis-ci.org/docker/docker-py.svg?branch=master
   :target: https://travis-ci.org/docker/docker-py
