> ## Documentation Index
> Fetch the complete documentation index at: https://aegean.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Running natively on Apple Silicon

> Installing the AI and computer vision environment directly on an M-series Mac so PyTorch can use the GPU through Metal.

On an Apple Silicon Mac, Docker cannot use the GPU. It runs containers inside a Linux virtual machine, where Apple's Metal framework is not available. That means PyTorch runs on the CPU inside the container, even on an M-series Mac.

For the **AI and computer vision** courses, you can install the project directly on macOS instead. This gives PyTorch access to the GPU through Apple's [Metal Performance Shaders](https://developer.apple.com/metal/pytorch/) backend, which appears in PyTorch as the `mps` device.

<Warning>
  This does not apply to the robotics course. ROS 2 still needs the container on macOS. See [ROS on Mac](/aiml-common/resources/environment/docker-containers#ros-on-mac).
</Warning>

## Native macOS or Docker?

Both options work, but each has a tradeoff.

**A native installation** uses your Mac's GPU, so training and other compute-heavy tasks are usually much faster. The downside is that you manage the dependencies yourself, and your installed versions may gradually differ from the course environment.

**The Docker container** gives you the same pinned environment used to run the notebooks on this site. This makes it easier to reproduce the published results, but the container can only use your Mac's CPU.

A practical approach is to work natively most of the time, then use the container or [Colab](https://colab.research.google.com) if a result looks suspicious and you want to rule out your local setup. Every assignment includes a Colab badge for this reason.

## Setup

You will need Python and `uv`. If you do not have them yet, follow the [Python and uv guide](/aiml-common/resources/environment/python-uv) first. The commands below assume that `uv` is available in your terminal.

```bash theme={null}
# Import your class repository to your own account, then clone it.
# Your assignment page links to the repository for your course.
git clone https://github.com/<your-username>/<class-repo>.git
cd <class-repo>

# Create the environment and install the project
uv venv
uv sync
```

That is all you need. The standard PyTorch package for Apple Silicon already includes Metal support, so there is no separate GPU package to install. CUDA is only for NVIDIA GPUs and is not used here.

## Selecting the device

Let PyTorch choose from the devices that are actually available instead of hard-coding one. With the following check, the same code can run on your Mac, a CUDA machine, or Colab:

```python theme={null}
import torch

if torch.cuda.is_available():
    device = torch.device("cuda")
elif torch.backends.mps.is_available():
    device = torch.device("mps")
else:
    device = torch.device("cpu")

print(f"torch {torch.__version__} on {device}")
```

On an M-series Mac, you should see `mps`. If the output says `cpu`, you are probably running inside a container or using a PyTorch build without Metal support.

## When an operation is not supported

PyTorch's Metal backend does not support every operation yet. If your model reaches an unsupported one, PyTorch stops with a runtime error that names the operator. You can tell it to run unsupported operations on the CPU instead:

```bash theme={null}
export PYTORCH_ENABLE_MPS_FALLBACK=1
```

If you need this regularly, add the variable to your shell profile. Keep in mind that frequent fallbacks can slow a model down because tensors have to move between the GPU and CPU. The [MPS backend documentation](https://docs.pytorch.org/docs/stable/notes/mps.html) has more detail about current support.

## A note about course notebooks

Some course notebooks only check for `cuda` and otherwise default to `cpu`. Those notebooks will still use the CPU on a Mac, even after you complete this setup. If you come across one, replace its device-selection code with the example above; that is usually the only change required.

***

<Callout icon="pen-to-square" iconType="regular">
  [Edit this page on GitHub](https://github.com/aegean-ai/eaia/edit/main/src/aiml-common/resources/environment/macos-native.mdx) or [file an issue](https://github.com/aegean-ai/eaia/issues/new/choose).
</Callout>