<commit_before>---
description: Getting Started
keywords: mac, edge, tutorial
redirect_from:
- /mackit/
- /mackit/getting-started/
- /mac/
- /mac/started/
- /docker-for-mac/started/
- /installation/mac/
- /engine/installation/mac/
- /docker-for-mac/index/
- /docker-for-mac/osx/
title: Get started with Docker for Mac
toc_max: 4
toc_min: 1
---

Welcome to Docker for Mac! Docker is a full development platform for creating
containerized apps, and Docker for Mac is the best way to get started with
Docker _on a Mac_.

> See [Install Docker for Mac](install.md){: target="_blank" class="_"} for information on system requirements and stable & edge channels.

## Check versions

Ensure your versions of `docker`, `docker-compose`, and `docker-machine` are up-to-date and compatible with `Docker.app`. Your output may differ if you are running different versions.

```shell
$ docker --version
Docker version {{ site.docker_ce_stable_version }}, build c97c6d6

$ docker-compose --version
docker-compose version {{ site.compose_version }}, build 8dd22a9

$ docker-machine --version
docker-machine version {{ site.machine_version }}, build 9ba6da9
```

## Explore the application

1.  Open a command-line terminal and test that your installation works by
    running the simple Docker image, [hello-world](https://hub.docker.com/_/hello-world/){: target="_blank" class="_"}:

    ```shell
    $ docker run hello-world

    Unable to find image 'hello-world:latest' locally
    latest: Pulling from library/hello-world
    ca4f61b1923c: Pull complete
    Digest: sha256:ca0eeb6fb05351dfc8759c20733c91def84cb8007aa89a5bf606bc8b315b9fc7
    Status: Downloaded newer image for hello-world:latest

    Hello from Docker!
    This message shows that your installation appears to be working correctly.
    ...
    ```

2.  Start a Dockerized web server. Like the hello-world image above, if the
    image is not found locally, Docker pulls it from Docker Hub.

    ```bash
    $ docker run -d -p 80:80 --name webserver nginx
    ```

3.  In a web browser, go to `http://localhost/` to view the nginx homepage. Because we specified the default HTTP port, it isn't necessary to append `:80` at the end of the URL.

    ![nginx home page](images/hello-world-nginx.png){:width="500px"}

    > Early beta releases used `docker` as the hostname to build the
    > URL. Now, ports are exposed on the private IP addresses of the VM and
    > forwarded to `localhost` with no other host name set.

4.  View the details on the container while your web server is running (with `docker container ls` or `docker ps`):

    ```none
    $ docker container ls
    CONTAINER ID   IMAGE   COMMAND                  CREATED              STATUS              PORTS                         NAMES
    56f433965490   nginx   "nginx -g 'daemon off"   About a minute ago   Up About a minute   0.0.0.0:80->80/tcp, 443/tcp   webserver
    ```

5.  Stop and remove containers and images with the following commands. Use the "all" flag (`--all` or `-a`) to view stopped containers.

    ```shell
    $ docker container ls
    $ docker container stop webserver
    $ docker container ls -a
    $ docker container rm webserver
    $ docker image ls
    $ docker image rm nginx
    ```

## Preferences menu

Choose ![whale menu](/docker-for-mac/images/whale-x.png){: .inline} -> **Preferences** from the menu bar and configure the runtime options described below.

![Docker context menu](images/menu/d4m-menu-prefs.png){:width="250px"}

### General tab

![Preferences](/docker-for-mac/images/menu/d4m-menu-prefs-general.png){:width="400px"}

Gneral settings are:

- **Start Docker when you log in**: Uncheck this option if you don't want Docker to start when you open your session.

- **Automatically check for updates** notifies you when an update is available.
  Click **OK** to accept and install updates (or cancel to keep the current
  version). If you disable this option, you can still find out about updates
  manually by choosing ![whale menu](/docker-for-mac/images/whale-x.png){: .inline} -> **Check for Updates**.

- **Include VM in Time Machine backups** backs up the Docker for Mac virtual machine. (Disabled by default.)

- **Securely store Docker logins in MacOS keychain** stores your Docker login credentials. (Enabled by default.)

- **Send usage statistics** &mdash; Send diagnostics, crash reports, and usage data to Docker. This information helps Docker improve the application and get more context for troubleshooting problems. (Enabled by default.)

### File sharing tab

Choose which local directories to share with your containers. File sharing is
required for volume mounting if the project lives outside of the `/Users`
directory. In that case, share the drive where the Dockerfile and volume are
located. Otherwise, you get `file not found` or `cannot start service errors at
runtime`.

![File Sharing](images/menu/d4m-menu-prefs-fileshare.png){:width="400px"}

File share settings are:

- **Add a Directory**: Click `+` and navigate to the directory you want to add.

- **Apply & Restart** makes the directory available to containers using Docker's bind mount (`-v`) feature.

  There are some limitations on the directories that can be shared:

  - They cannot be a subdirectory of an already shared directory.
  - They cannot already exist inside of Docker.

For more information, see:

- [Namespaces](osxfs.md#namespaces){: target="_blank" class="_"} in the topic on [osxfs file system sharing](osxfs.md).
- [Volume mounting requires file sharing for any project directories outside of `/Users`](troubleshoot.md#volume-mounting-requires-file-sharing-for-any-project-directories-outside-of-users).)

### Advanced tab

On the Advanced tab, you can limit resources available to Docker.

![Advanced Preference settings-advanced](images/menu/d4m-menu-prefs-advanced.png){:width="400px"}

Advanced settings are:

**CPUs**: By default, Docker for Mac is set to use half the number of processors available
on the host machine. To increase processing power, set this to a higher number;
to decrease, lower the number.

**Memory**: By default, Docker for Mac is set to use `2` GB runtime memory, allocated from
the total available memory on your Mac. To increase RAM, set this to a higher number;
to decrease it, lower the number.

**Swap**: Configure swappiness as needed. The default is 1.

### Disk tab

Specify the **Disk image location** of the Linux volume, where containers and images are stored.

You can also move the disk image location. If you attempt to move the disk image
to a location that already has one, you get a prompt asking if you want to use
the existing image or replace it.

![Proxies settings](/docker-for-mac/images/menu/d4m-menu-prefs-disk.png){:width="400px"}
<commit_msg>Update description of swap parameter (#6265)<commit_after>---
description: Getting Started
keywords: mac, edge, tutorial
redirect_from:
- /mackit/
- /mackit/getting-started/
- /mac/
- /mac/started/
- /docker-for-mac/started/
- /installation/mac/
- /engine/installation/mac/
- /docker-for-mac/index/
- /docker-for-mac/osx/
title: Get started with Docker for Mac
toc_max: 4
toc_min: 1
---

Welcome to Docker for Mac! Docker is a full development platform for creating
containerized apps, and Docker for Mac is the best way to get started with
Docker _on a Mac_.

> See [Install Docker for Mac](install.md){: target="_blank" class="_"} for information on system requirements and stable & edge channels.

## Check versions

Ensure your versions of `docker`, `docker-compose`, and `docker-machine` are up-to-date and compatible with `Docker.app`. Your output may differ if you are running different versions.

```shell
$ docker --version
Docker version {{ site.docker_ce_stable_version }}, build c97c6d6

$ docker-compose --version
docker-compose version {{ site.compose_version }}, build 8dd22a9

$ docker-machine --version
docker-machine version {{ site.machine_version }}, build 9ba6da9
```

## Explore the application

1.  Open a command-line terminal and test that your installation works by
    running the simple Docker image, [hello-world](https://hub.docker.com/_/hello-world/){: target="_blank" class="_"}:

    ```shell
    $ docker run hello-world

    Unable to find image 'hello-world:latest' locally
    latest: Pulling from library/hello-world
    ca4f61b1923c: Pull complete
    Digest: sha256:ca0eeb6fb05351dfc8759c20733c91def84cb8007aa89a5bf606bc8b315b9fc7
    Status: Downloaded newer image for hello-world:latest

    Hello from Docker!
    This message shows that your installation appears to be working correctly.
    ...
    ```

2.  Start a Dockerized web server. Like the hello-world image above, if the
    image is not found locally, Docker pulls it from Docker Hub.

    ```bash
    $ docker run -d -p 80:80 --name webserver nginx
    ```

3.  In a web browser, go to `http://localhost/` to view the nginx homepage. Because we specified the default HTTP port, it isn't necessary to append `:80` at the end of the URL.

    ![nginx home page](images/hello-world-nginx.png){:width="500px"}

    > Early beta releases used `docker` as the hostname to build the
    > URL. Now, ports are exposed on the private IP addresses of the VM and
    > forwarded to `localhost` with no other host name set.

4.  View the details on the container while your web server is running (with `docker container ls` or `docker ps`):

    ```none
    $ docker container ls
    CONTAINER ID   IMAGE   COMMAND                  CREATED              STATUS              PORTS                         NAMES
    56f433965490   nginx   "nginx -g 'daemon off"   About a minute ago   Up About a minute   0.0.0.0:80->80/tcp, 443/tcp   webserver
    ```

5.  Stop and remove containers and images with the following commands. Use the "all" flag (`--all` or `-a`) to view stopped containers.

    ```shell
    $ docker container ls
    $ docker container stop webserver
    $ docker container ls -a
    $ docker container rm webserver
    $ docker image ls
    $ docker image rm nginx
    ```

## Preferences menu

Choose ![whale menu](/docker-for-mac/images/whale-x.png){: .inline} -> **Preferences** from the menu bar and configure the runtime options described below.

![Docker context menu](images/menu/d4m-menu-prefs.png){:width="250px"}

### General tab

![Preferences](/docker-for-mac/images/menu/d4m-menu-prefs-general.png){:width="400px"}

Gneral settings are:

- **Start Docker when you log in**: Uncheck this option if you don't want Docker to start when you open your session.

- **Automatically check for updates** notifies you when an update is available.
  Click **OK** to accept and install updates (or cancel to keep the current
  version). If you disable this option, you can still find out about updates
  manually by choosing ![whale menu](/docker-for-mac/images/whale-x.png){: .inline} -> **Check for Updates**.

- **Include VM in Time Machine backups** backs up the Docker for Mac virtual machine. (Disabled by default.)

- **Securely store Docker logins in MacOS keychain** stores your Docker login credentials. (Enabled by default.)

- **Send usage statistics** &mdash; Send diagnostics, crash reports, and usage data to Docker. This information helps Docker improve the application and get more context for troubleshooting problems. (Enabled by default.)

### File sharing tab

Choose which local directories to share with your containers. File sharing is
required for volume mounting if the project lives outside of the `/Users`
directory. In that case, share the drive where the Dockerfile and volume are
located. Otherwise, you get `file not found` or `cannot start service errors at
runtime`.

![File Sharing](images/menu/d4m-menu-prefs-fileshare.png){:width="400px"}

File share settings are:

- **Add a Directory**: Click `+` and navigate to the directory you want to add.

- **Apply & Restart** makes the directory available to containers using Docker's bind mount (`-v`) feature.

  There are some limitations on the directories that can be shared:

  - They cannot be a subdirectory of an already shared directory.
  - They cannot already exist inside of Docker.

For more information, see:

- [Namespaces](osxfs.md#namespaces){: target="_blank" class="_"} in the topic on [osxfs file system sharing](osxfs.md).
- [Volume mounting requires file sharing for any project directories outside of `/Users`](troubleshoot.md#volume-mounting-requires-file-sharing-for-any-project-directories-outside-of-users).)

### Advanced tab

On the Advanced tab, you can limit resources available to Docker.

![Advanced Preference settings-advanced](images/menu/d4m-menu-prefs-advanced.png){:width="400px"}

Advanced settings are:

**CPUs**: By default, Docker for Mac is set to use half the number of processors available
on the host machine. To increase processing power, set this to a higher number;
to decrease, lower the number.

**Memory**: By default, Docker for Mac is set to use `2` GB runtime memory, allocated from
the total available memory on your Mac. To increase RAM, set this to a higher number;
to decrease it, lower the number.

**Swap**: Configure swap file size as needed. The default is 1 GB.

### Disk tab

Specify the **Disk image location** of the Linux volume, where containers and images are stored.

You can also move the disk image location. If you attempt to move the disk image
to a location that already has one, you get a prompt asking if you want to use
the existing image or replace it.

![Proxies settings](/docker-for-mac/images/menu/d4m-menu-prefs-disk.png){:width="400px"}

{'fraction_non_alphanumeric': 0.0949823425544438, 'fraction_numerical': 0.017510300176574456, 'mean_word_length': 3.747816975200838, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 17, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6503440', 'n_tokens_mistral': 4145, 'n_tokens_neox': 3778, 'n_words': 1692}