<p>According to the Docker documentation:</p>
<blockquote>
<p><code>docker-compose run</code> runs a one-time command against a service. [...]</p>
<p>Commands you use with <code>run</code> start in new containers with configuration defined by that of the service, including volumes, links, and other details. However, there are two important differences.</p>
<p>First, the command passed by <code>run</code> overrides the command defined in the service configuration. [...]</p>
<p>The second difference is that the <code>docker-compose run</code> command does not create any of the ports specified in the service configuration. This prevents port collisions with already-open ports. If you do want the service’s ports to be created and mapped to the host, specify the --service-ports flag:</p>
<p><code>docker-compose run --service-ports web python manage.py shell</code></p>
<p>Alternatively, manual port mapping can be specified with the <code>--publish</code> or <code>-p</code> options, just as when using docker run:</p>
<p><code>docker-compose run --publish 8080:80 -p 2022:22 -p 127.0.0.1:2021:21 web python manage.py shell</code></p>
</blockquote>
<p>This is meant so that you can run singular commands against an already defined service or services using <code>docker-compose run</code>.</p>
<p>For example, lets say you set up a compose file that defines some kind of service. To start the service to run in the background you use <code>docker-compose -f &lt;FILE&gt; up --detach</code> but if you wanted to look inside the container using a terminal, you would run <code>docker-compose run bash</code>.</p>
<p>The reason for the ports being ignored is <code>docker-compose run</code> assumes the container is already set up, and has it's ports set up correctly. If you ran a script that did something involving ports using <code>docker-compose run /path/to/script.sh</code> you might not want it to change the ports that were correctly mapped with your <code>docker-compose up</code> command. This way, the option makes it so you have to tell docker explicitly &quot;I actually want port mappings to change&quot;.</p>

CC BY-SA 4.0
2019-03-07T14:04:19.170Z
I see, that makes sense. Thank you for explaining!
Worp
CC BY-SA 4.0
2019-02-07T20:40:48.603Z
2019-02-07T20:40:48.603Z
2020-06-18T08:28:10.803Z
Wimateeka
<p>Docker-compose's run reference includes the "--service-ports" flag.</p>

<pre><code> --service-ports       Run command with the service's ports enabled and mapped
                      to the host.
</code></pre>

<p>Source: <a href="https://docs.docker.com/compose/reference/run/" rel="noreferrer">https://docs.docker.com/compose/reference/run/</a></p>

<p>The description doesn't really tell me anything. Ports are mapped to the host on <code>docker-compose up</code> if I specify them in the docker-compose file. No matter if the flag is used or not.</p>

<p>What is it for?</p>

<docker><docker-compose>
When would I use docker-compose's "--service-ports" flag?
Worp
# When would I use docker-compose's "--service-ports" flag?

(Asked by: username_0 on 2019-02-05)

Docker-compose's run reference includes the "--service-ports" flag.
 --service-ports       Run command with the service's ports enabled and mapped
                      to the host.

Source: https://docs.docker.com/compose/reference/run/
The description doesn't really tell me anything. Ports are mapped to the host on docker-compose up if I specify them in the docker-compose file. No matter if the flag is used or not.
What is it for?

**Tags:** docker, docker-compose


---

## 1 answers

### Answer by username_1 on 2019-02-07. Score: 8 | Accepted answer

According to the Docker documentation:

> `docker-compose run` runs a one-time command against a service. [...]
>
> Commands you use with `run` start in new containers with configuration defined by that of the service, including volumes, links, and other details. However, there are two important differences.
>
> First, the command passed by `run` overrides the command defined in the service configuration. [...]
>
> The second difference is that the `docker-compose run` command does not create any of the ports specified in the service configuration. This prevents port collisions with already-open ports. If you do want the service’s ports to be created and mapped to the host, specify the --service-ports flag:
>
> `docker-compose run --service-ports web python manage.py shell`
>
> Alternatively, manual port mapping can be specified with the `--publish` or `-p` options, just as when using docker run:
>
> `docker-compose run --publish 8080:80 -p 2022:22 -p 127.0.0.1:2021:21 web python manage.py shell`

This is meant so that you can run singular commands against an already defined service or services using `docker-compose run`.

For example, lets say you set up a compose file that defines some kind of service. To start the service to run in the background you use `docker-compose -f  up --detach` but if you wanted to look inside the container using a terminal, you would run `docker-compose run bash`.

The reason for the ports being ignored is `docker-compose run` assumes the container is already set up, and has it's ports set up correctly. If you ran a script that did something involving ports using `docker-compose run /path/to/script.sh` you might not want it to change the ports that were correctly mapped with your `docker-compose up` command. This way, the option makes it so you have to tell docker explicitly "I actually want port mappings to change".

> **Comments:**
> **username_0**: I see, that makes sense. Thank you for explaining!  

---

