path: root/docs/api.md

# Client API

To instantiate a `Client` class that will allow you to communicate with a 
Docker daemon, simply do:

```python
from docker import Client
c = Client(base_url='unix://var/run/docker.sock')
```

**Params**:

* base_url (str): Refers to the protocol+hostname+port where the Docker server 
is hosted.
* version (str): The version of the API the client will use
* timeout (int): The HTTP request timeout, in seconds.
* tls (bool or [TLSConfig](tls.md#TLSConfig)): Equivalent CLI options: `docker --tls ...`

****

## attach

The `.logs()` function is a wrapper around this method, which you can use 
instead if you want to fetch/stream container output without first retrieving 
the entire backlog.

**Params**:

* container (str): The container to attach to
* stdout (bool): Get STDOUT
* stderr (bool): Get STDERR
* stream (bool): Return an interator
* logs (bool): Get all previous output

**Returns** (generator or str): The logs or output for the image

## build

Similar to the `docker build` command. Either `path` or `fileobj` needs to be 
set. `path` can be a local path (to a directory containing a Dockerfile) or a 
remote URL. `fileobj` must be a readable file-like object to a Dockerfile.

If you have a tar file for the Docker build context (including a Dockerfile) 
already, pass a readable file-like object to `fileobj` and also pass 
`custom_context=True`. If the stream is compressed also, set `encoding` to the 
correct value (e.g `gzip`).

**Params**:

* path (str): Path to the directory containing the Dockerfile
* tag (str): A tag to add to the final image
* quiet (bool): Whether to return the status
* fileobj: A file object to use as the Dockerfile. (Or a file-like object)
* nocache (bool): Don't use the cache when set to `True`
* rm (bool): Remove intermediate containers
* stream (bool): Return a blocking generator you can iterate over to retrieve 
build output as it happens
* timeout (int): HTTP timeout
* custom_context (bool): Optional if using `fileobj`
* encoding (str): The encoding for a stream. Set to `gzip` for compressing

**Returns** (generator): A generator of the build output

```python
>>> from io import BytesIO
>>> from docker import Client
>>> dockerfile = '''
... # Shared Volume
... FROM busybox:buildroot-2014.02
... MAINTAINER first last, first.last@yourdomain.com
... VOLUME /data
... CMD ["/bin/sh"]
... '''
>>> f = BytesIO(dockerfile.encode('utf-8'))
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> response = [line for line in cli.build(
...     fileobj=f, rm=True, tag='yourname/volume'
... )]
>>> response
['{"stream":" ---\\u003e a9eb17255234\\n"}',
'{"stream":"Step 1 : MAINTAINER first last, first.last@yourdomain.com\\n"}',
'{"stream":" ---\\u003e Running in 08787d0ee8b1\\n"}',
'{"stream":" ---\\u003e 23e5e66a4494\\n"}',
'{"stream":"Removing intermediate container 08787d0ee8b1\\n"}',
'{"stream":"Step 2 : VOLUME /data\\n"}',
'{"stream":" ---\\u003e Running in abdc1e6896c6\\n"}',
'{"stream":" ---\\u003e 713bca62012e\\n"}',
'{"stream":"Removing intermediate container abdc1e6896c6\\n"}',
'{"stream":"Step 3 : CMD [\\"/bin/sh\\"]\\n"}',
'{"stream":" ---\\u003e Running in dba30f2a1a7e\\n"}',
'{"stream":" ---\\u003e 032b8b2855fc\\n"}',
'{"stream":"Removing intermediate container dba30f2a1a7e\\n"}',
'{"stream":"Successfully built 032b8b2855fc\\n"}']
```

**Raises:** [TypeError](
https://docs.python.org/3.4/library/exceptions.html#TypeError) if `path` nor 
`fileobj` are specified

## commit

Identical to the `docker commit` command.

**Params**:

* container (str): The image hash of the container
* repository (str): The repository to push the image to
* tag (str): The tag to push
* message (str): A commit message
* author (str): The name of the author
* conf (dict): The configuraton for the container. See the [Docker remote api](
https://docs.docker.com/reference/api/docker_remote_api/) for full details.

## containers

List containers. Identical to the `docker ps` command.

**Params**:

* quiet (bool): Only display numeric Ids
* all (bool): Show all containers. Only running containers are shown by default
* trunc (bool): Truncate output
* latest (bool): Show only the latest created container, include non-running
ones.
* since (str): Show only containers created since Id or Name, include 
non-running ones
* before (str): Show only container created before Id or Name, include 
non-running ones
* limit (int): Show `limit` last created containers, include non-running ones
* size (bool): Display sizes

**Returns** (dict): The system's containers

```python
>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> cli.containers()
[{'Command': '/bin/sleep 30',
  'Created': 1412574844,
  'Id': '6e276c9e6e5759e12a6a9214efec6439f80b4f37618e1a6547f28a3da34db07a',
  'Image': 'busybox:buildroot-2014.02',
  'Names': ['/grave_mayer'],
  'Ports': [],
  'Status': 'Up 1 seconds'}]
```

## copy
Identical to the `docker cp` command. Get files/folders from the container.

**Params**:

* container (str): The container to copy from
* resource (str): The path within the container

**Returns** (str): The contents of the file as a string

## create_container

Creates a container that can then be `.start()` ed. Parameters are similar to 
those for the `docker run` command except it doesn't support the attach 
options (`-a`).

See [Port bindings](port-bindings.md) and [Using volumes](volumes.md) for more 
information on how to create port bindings and volume mappings.

The `mem_limit` variable accepts float values (which represent the memory limit 
of the created container in bytes) or a string with a units identification char 
('100000b', 1000k', 128m', '1g'). If a string is specified without a units 
character, bytes are assumed as an intended unit.

`volumes_from` and `dns` arguments raise [TypeError](
https://docs.python.org/3.4/library/exceptions.html#TypeError) exception if 
they are used against v1.10 of the Docker remote API. Those arguments should be 
passed to `start()` instead.

**Params**:

* image (str): The image to run
* command (str or list): The command to be run in the container
* hostname (str): Optional hostname for the container
* user (str or int): Username or UID
* detach (bool): Detached mode: run container in the background and print new 
container Id
* stdin_open (bool): Keep STDIN open even if not attached
* tty (bool): Allocate a pseudo-TTY
* mem_limit (float or str): Memory limit (format: [number][optional unit], 
where unit = b, k, m, or g)
* ports (list of ints): A list of port numbers
* environment (dict or list): A dictionary or a list of strings in the 
following format `["PASSWORD=xxx"]` or `{"PASSWORD": "xxx"}`.
* dns (list): DNS name servers
* volumes (str or list): 
* volumes_from (str or list): List of container names or Ids to get volumes 
from. Optionally a single string joining container id's with commas
* network_disabled (bool): Disable networking
* name (str): A name for the container
* entrypoint (str or list): An entrypoint
* cpu_shares (int or float): CPU shares (relative weight)
* working_dir (str): Path to the working directory
* domainname (str or list): Set custom DNS search domains
* memswap_limit:

**Returns** (dict): A dictionary with an image 'Id' key and a 'Warnings' key.

```python
>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> container = cli.create_container(image='busybox:latest', command='/bin/sleep 30')
>>> print(container)
{'Id': '8a61192da2b3bb2d922875585e29b74ec0dc4e0117fcbf84c962204e97564cd7',
 'Warnings': None}
```

## diff

Inspect changes on a container's filesystem

**Params**:

* container (str): The container to diff

**Returns** (str):

## execute

```python
c.execute(container, cmd, detach=False, stdout=True, stderr=True,
       stream=False, tty=False)
```

Execute a command in a running container.

**Params**:

* container (str): can be a container dictionary (result of
running `inspect_container`), unique id or container name.


* cmd (str or list): representing the command and its arguments.

* detach (bool): flag to `True` will run the process in the background.

* stdout (bool): indicates which output streams to read from.
* stderr (bool): indicates which output streams to read from.

* stream (bool): indicates whether to return a generator which will yield
  the streaming response in chunks.

## export

Export the contents of a filesystem as a tar archive to STDOUT

**Params**:

* container (str): The container to export

**Returns** (str): The filesystem tar archive as a str

## history

Show the history of an image

**Params**:

* image (str): The image to show history for

**Returns** (str): The history of the image

## images

List images. Identical to the `docker images` command.

**Params**:

* name (str): Optional filter for a name
* quiet (bool): Only show numeric Ids. Returns a list
* all (bool): Show all images (by default filter out the intermediate image
layers)
* viz: *Depreciated*

**Returns** (dict or list): A list if `quiet=True`, otherwise a dict.

```python
[{'Created': 1401926735,
'Id': 'a9eb172552348a9a49180694790b33a1097f546456d041b6e82e4d7716ddb721',
'ParentId': '120e218dd395ec314e7b6249f39d2853911b3d6def6ea164ae05722649f34b16',
'RepoTags': ['busybox:buildroot-2014.02', 'busybox:latest'],
'Size': 0,
'VirtualSize': 2433303},
...
```

## import_image

Identical to the `docker import` command. If `src` is a string or unicode 
string, it will be treated as a URL to fetch the image from. To import an image 
from the local machine, `src` needs to be a file-like object or bytes 
collection.  To import from a tarball use your absolute path to your tarball. 
To load arbitrary data as tarball use whatever you want as src and your 
tarball content in data.

**Params**:

* src (str or file): Path to tarfile or URL
* repository (str): The repository to create
* tag (str): The tag to apply
* image (str): Use another image like the `FROM` Dockerfile parameter

## info

Display system-wide information. Identical to the `docker info` command.

**Returns** (dict): The info as a dict

```
>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> cli.info()
{'Containers': 3,
 'Debug': 1,
 'Driver': 'aufs',
 'DriverStatus': [['Root Dir', '/mnt/sda1/var/lib/docker/aufs'],
  ['Dirs', '225']],
 'ExecutionDriver': 'native-0.2',
 'IPv4Forwarding': 1,
 'Images': 219,
 'IndexServerAddress': 'https://index.docker.io/v1/',
 'InitPath': '/usr/local/bin/docker',
 'InitSha1': '',
 'KernelVersion': '3.16.1-tinycore64',
 'MemoryLimit': 1,
 'NEventsListener': 0,
 'NFd': 11,
 'NGoroutines': 12,
 'OperatingSystem': 'Boot2Docker 1.2.0 (TCL 5.3);',
 'SwapLimit': 1}
```

## insert
*DEPRECATED*

## inspect_container

Identical to the `docker inspect` command, but only for containers.

**Params**:

* container (str): The container to inspect

**Returns** (dict): Nearly the same output as `docker inspect`, just as a 
single dict

## inspect_image

Identical to the `docker inspect` command, but only for images

**Params**:

* image_id (str): The image to inspect

**Returns** (dict): Nearly the same output as `docker inspect`, just as a 
single dict

## kill

Kill a container or send a signal to a container

**Params**:

* container (str): The container to kill
* signal (str or int): The singal to send. Defaults to `SIGKILL`

## login

Nearly identical to the `docker login` command, but non-interactive.

**Params**:

* username (str): The registry username
* password (str): The plaintext password
* email (str): The email for the registry account
* registry (str): URL to the registry. Ex:`https://index.docker.io/v1/`
* reauth (bool): Whether refresh existing authentication on the docker server.

**Returns** (dict): The response from the login request

## logs

Identical to the `docker logs` command. The `stream` parameter makes the `logs`
function return a blocking generator you can iterate over to retrieve log 
output as it happens.

**Params**:

* container (str): The container to get logs from
* stdout (bool): Get STDOUT
* stderr (bool): Get STDERR
* stream (bool): Stream the response
* timestamps (bool): Show timestamps

**Returns** (generator or str):

## pause

Pauses all processes within a container.

**Params**:

* container (str): The container to pause


## ping

Hits the `/_ping` endpoint of the remote API and returns the result. An 
exception will be raised if the endpoint isn't responding.

**Returns** (bool)

## port
Lookup the public-facing port that is NAT-ed to `private_port`. Identical to 
the `docker port` command.

**Params**:

* container (str): The container to look up
* private_port (int): The private port to inspect

**Returns** (list of dict): The mapping for the host ports

```bash
$ docker run -d -p 80:80 ubuntu:14.04 /bin/sleep 30
7174d6347063a83f412fad6124c99cffd25ffe1a0807eb4b7f9cec76ac8cb43b
```
```python
>>> cli.port('7174d6347063', 80)
[{'HostIp': '0.0.0.0', 'HostPort': '80'}]
```

## pull

Identical to the `docker pull` command.

**Params**:

* repository (str): The repository to pull
* tag (str): The tag to pull
* stream (bool): Stream the output as a generator
* insecure_registry (bool): Use an insecure registry

**Returns** (generator or str): The output

```python
>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> for line in cli.pull('busybox', stream=True):
...     print(json.dumps(json.loads(line), indent=4))
{
    "status": "Pulling image (latest) from busybox",
    "progressDetail": {},
    "id": "e72ac664f4f0"
}
{
    "status": "Pulling image (latest) from busybox, endpoint: ...",
    "progressDetail": {},
    "id": "e72ac664f4f0"
}
```

## push

Push an image or a repository to the registry. Identical to the `docker push` 
command

**Params**:

* repository (str): The repository to push to
* tag (str): An optional tag to push
* stream (bool): Stream the output as a blocking generator
* insecure_registry (bool): Use `http://` to connect to the registry

**Returns** (generator or str): The output of the upload

```python
>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> response = [line for line in cli.push('yourname/app', stream=True)]
>>> response
['{"status":"Pushing repository yourname/app (1 tags)"}\\n',
 '{"status":"Pushing","progressDetail":{},"id":"511136ea3c5a"}\\n',
 '{"status":"Image already pushed, skipping","progressDetail":{},
    "id":"511136ea3c5a"}\\n',
 ...
 '{"status":"Pushing tag for rev [918af568e6e5] on {
    https://cdn-registry-1.docker.io/v1/repositories/
    yourname/app/tags/latest}"}\\n']
```

## remove_container

Remove a container. Similar to the `docker rm` command.

**Params**:

* container (str): The container to remove
* v (bool): Remove the volumes associated with the container
* link (bool): Remove the specified link and not the underlying container
* force (bool): Force the removal of a running container (uses SIGKILL)

## remove_image

Remove an image. Similar to the `docker rmi` command.

**Params**:

* image (str): The image to remove
* force (bool): Force removal of the image
* noprune (bool): Do not delete untagged parents

## restart

Restart a container. Similar to the `docker restart` command.

If `container` a dict, the `Id` key is used.

**Params**:

* container (str or dict): The container to restart
* timeout (int): Number of seconds to try to stop for before killing the 
container. Once killed it will then be restarted. Default is 10 seconds.

## search
Identical to the `docker search` command.

**Params**:

* term (str): A term to search for

**Returns** (list of dicts): The response of the search

```python
>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> response = cli.search('nginx')
>>> response[:2]
[{'description': 'Official build of Nginx.',
  'is_official': True,
  'is_trusted': False,
  'name': 'nginx',
  'star_count': 266},
 {'description': 'Trusted automated Nginx (http://nginx.org/) ...',
  'is_official': False,
  'is_trusted': True,
  'name': 'dockerfile/nginx',
  'star_count': 60},
  ...
```
 
## start
 
Similar to the `docker start` command, but doesn't support attach options. Use
`.logs()` to recover `stdout`/`stderr`.

`binds` allows to bind a directory in the host to the container. See [Using 
volumes](volumes.md) for more information. `port_bindings` exposes container 
ports to the host. See [Port bindings](port-bindings.md) for more information.
`lxc_conf` allows to pass LXC configuration options using a dictionary. 
`privileged` starts the container in privileged mode.

[Links](http://docs.docker.io/en/latest/use/working_with_links_names/) can be 
specified with the `links` argument. They can either be specified as a 
dictionary mapping name to alias or as a list of `(name, alias)` tuples.

`dns` and `volumes_from` are only available if they are used with version v1.10
of docker remote API. Otherwise they are ignored.

`network_mode` is available since v1.11 and sets the Network mode for the 
container ('bridge': creates a new network stack for the container on the 
Docker bridge, 'none': no networking for this container, 'container:[name|id]': 
reuses another container network stack), 'host': use the host network stack 
inside the container.

`restart_policy` is available since v1.2.0 and sets the RestartPolicy for how a
container should or should not be restarted on exit. By default the policy is 
set to no meaning do not restart the container when it exits. The user may 
specify the restart policy as a dictionary for example:
```python
{
    "MaximumRetryCount": 0,
    "Name": "always"
}
```

For always restarting the container on exit or can specify to restart the 
container to restart on failure and can limit number of restarts. For example:
```python
{
    "MaximumRetryCount": 5,
    "Name": "on-failure"
}
```

`cap_add` and `cap_drop` are available since v1.2.0 and can be used to add or 
drop certain capabilities. The user may specify the capabilities as an array 
for example:
```python
[
    "SYS_ADMIN",
    "MKNOD"
]
```

**Params**:

* container (str): The container to start
* binds: Volumes to bind
* port_bindings (dict): Port bindings. See note above
* lxc_conf (dict): LXC config
* publish_all_ports (bool): Whether to publish all ports to the host
* links (dict or list of tuples): See note above
* privileged (bool): Give extended privileges to this container
* dns (list): Set custom DNS servers
* dns_search (list): DNS search  domains
* volumes_from (str or list): List of container names or Ids to get volumes 
from. Optionally a single string joining container id's with commas
* network_mode (str): One of `['bridge', None, 'container:<name|id>',
'host']`
* restart_policy (dict): See note above. "Name" param must be one of 
`['on-failure', 'always']`
* cap_add (list of str): See note above
* cap_drop (list of str): See note above

```python
>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> container = cli.create_container(
...     image='busybox:latest',
...     command='/bin/sleep 30')
>>> response = cli.start(container=container.get('Id'))
>>> print(response)
None
```

## stop

Stops a container. Similar to the `docker stop` command.

**Params**:

* container (str): The container to stop
* timeout (int): Timeout in seconds to wait for the container to stop before 
sending a `SIGKILL`

## tag

Tag an image into a repository. Identical to the `docker tag` command.

**Params**:

* image (str): The image to tag
* repository (str): The repository to set for the tag
* tag (str): The tag name
* force (bool): Force

**Returns** (bool): True if successful

## top
Display the running processes of a container

**Params**:

* container (str): The container to inspect

**Returns** (str): The output of the top

```python
>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> cli.create_container('busybox:latest', '/bin/sleep 30', name='sleeper')
>>> cli.start('sleeper')
>>> cli.top('sleeper')
{'Processes': [['952', 'root', '/bin/sleep 30']],
 'Titles': ['PID', 'USER', 'COMMAND']}
```

## unpause

Unpauses all processes within a container.

**Params**:

* container (str): The container to unpause

## version
Nearly identical to the `docker version` command. 

**Returns** (dict): The server version information

```python
>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> cli.version()
{
    "KernelVersion": "3.16.4-tinycore64", 
    "Arch": "amd64", 
    "ApiVersion": "1.15", 
    "Version": "1.3.0", 
    "GitCommit": "c78088f", 
    "Os": "linux", 
    "GoVersion": "go1.3.3"
}
```


## wait
Identical to the `docker wait` command. Block until a container stops, then 
print its exit code. Returns the value `-1` if no `StatusCode` is returned by 
the API.

If `container` a dict, the `Id` key is used.

**Params**:

* container (str or dict): The container to wait on

**Returns** (int): The exit code of the container


<!---
TODO:

* events
* get_image
* load_image
* resize

-->