github.com/panekj/cli@v0.0.0-20230304125325-467dd2f3797e/docs/reference/commandline/exec.md (about)

     1  # exec
     2  
     3  <!---MARKER_GEN_START-->
     4  Execute a command in a running container
     5  
     6  ### Aliases
     7  
     8  `docker container exec`, `docker exec`
     9  
    10  ### Options
    11  
    12  | Name                                      | Type     | Default | Description                                            |
    13  |:------------------------------------------|:---------|:--------|:-------------------------------------------------------|
    14  | `-d`, `--detach`                          |          |         | Detached mode: run command in the background           |
    15  | `--detach-keys`                           | `string` |         | Override the key sequence for detaching a container    |
    16  | [`-e`](#env), [`--env`](#env)             | `list`   |         | Set environment variables                              |
    17  | `--env-file`                              | `list`   |         | Read in a file of environment variables                |
    18  | `-i`, `--interactive`                     |          |         | Keep STDIN open even if not attached                   |
    19  | `--privileged`                            |          |         | Give extended privileges to the command                |
    20  | `-t`, `--tty`                             |          |         | Allocate a pseudo-TTY                                  |
    21  | `-u`, `--user`                            | `string` |         | Username or UID (format: `<name\|uid>[:<group\|gid>]`) |
    22  | [`-w`](#workdir), [`--workdir`](#workdir) | `string` |         | Working directory inside the container                 |
    23  
    24  
    25  <!---MARKER_GEN_END-->
    26  
    27  ## Description
    28  
    29  The `docker exec` command runs a new command in a running container.
    30  
    31  The command started using `docker exec` only runs while the container's primary
    32  process (`PID 1`) is running, and it is not restarted if the container is
    33  restarted.
    34  
    35  COMMAND runs in the default directory of the container. If the underlying image
    36  has a custom directory specified with the WORKDIR directive in its Dockerfile,
    37  this directory is used instead.
    38  
    39  COMMAND must be an executable. A chained or a quoted command does not work.
    40  For example, `docker exec -it my_container sh -c "echo a && echo b"` does
    41  work, but `docker exec -it my_container "echo a && echo b"` does not.
    42  
    43  ## Examples
    44  
    45  ### Run `docker exec` on a running container
    46  
    47  First, start a container.
    48  
    49  ```console
    50  $ docker run --name mycontainer -d -i -t alpine /bin/sh
    51  ```
    52  
    53  This creates and starts a container named `mycontainer` from an `alpine` image
    54  with an `sh` shell as its main process. The `-d` option (shorthand for `--detach`)
    55  sets the container to run in the background, in detached mode, with a pseudo-TTY
    56  attached (`-t`). The `-i` option is set to keep `STDIN` attached (`-i`), which
    57  prevents the `sh` process from exiting immediately.
    58  
    59  Next, execute a command on the container.
    60  
    61  ```console
    62  $ docker exec -d mycontainer touch /tmp/execWorks
    63  ```
    64  
    65  This creates a new file `/tmp/execWorks` inside the running container
    66  `mycontainer`, in the background.
    67  
    68  Next, execute an interactive `sh` shell on the container.
    69  
    70  ```console
    71  $ docker exec -it mycontainer sh
    72  ```
    73  
    74  This starts a new shell session in the container `mycontainer`.
    75  
    76  ### <a name="env"></a> Set environment variables for the exec process (--env, -e)
    77  
    78  Next, set environment variables in the current bash session.
    79  
    80  By default, the `docker exec` command, inherits the environment variables that
    81  are set at the time the container is created. Use the `--env` (or the `-e` shorthand)
    82  to override global environment variables, or to set additional environment variables
    83  for the process started by `docker exec`.
    84  
    85  The example below creates a new shell session in the container `mycontainer` with
    86  environment variables `$VAR_A` and `$VAR_B` set to "1" and "2" respectively.
    87  These environment variables are only valid for the `sh` process started by that
    88  `docker exec` command, and are not available to other processes running inside
    89  the container.
    90  
    91  ```console
    92  $ docker exec -e VAR_A=1 -e VAR_B=2 mycontainer env
    93  PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    94  HOSTNAME=f64a4851eb71
    95  VAR_A=1
    96  VAR_B=2
    97  HOME=/root
    98  ```
    99  
   100  ### <a name="workdir"></a> Set the working directory for the exec process (--workdir, -w)
   101  
   102  By default `docker exec` command runs in the same working directory set when 
   103  the container was created.
   104  
   105  ```console
   106  $ docker exec -it mycontainer pwd
   107  /
   108  ```
   109  
   110  You can specify an alternative working directory for the command to execute 
   111  using the `--workdir` option (or the `-w` shorthand):
   112  
   113  ```console
   114  $ docker exec -it -w /root mycontainer pwd
   115  /root
   116  ```
   117  
   118  
   119  ### Try to run `docker exec` on a paused container
   120  
   121  If the container is paused, then the `docker exec` command fails with an error:
   122  
   123  ```console
   124  $ docker pause mycontainer
   125  mycontainer
   126  
   127  $ docker ps
   128  
   129  CONTAINER ID   IMAGE     COMMAND     CREATED          STATUS                   PORTS     NAMES
   130  482efdf39fac   alpine    "/bin/sh"   17 seconds ago   Up 16 seconds (Paused)             mycontainer
   131  
   132  $ docker exec mycontainer sh
   133  
   134  Error response from daemon: Container mycontainer is paused, unpause the container before exec
   135  
   136  $ echo $?
   137  1
   138  ```