ROS 2: Zero to MoveIt 2 › Module 0 › Mac
Set up ROS 2 on a Mac
6 steps About 2 to 3 hours for both guides, mostly waiting Not tested on a real Mac yet
Your route: an Ubuntu 24.04 virtual machine (UTM) in the 6 steps here, then the 12 steps of the Ubuntu guide inside it. Do one step at a time. Each step says what to do, how long it takes, what you should see, and what to do when you are stuck. No step touches your own files, and you can stop after any step.
Written from UTM's and Ubuntu's own documents; not run on a real Mac yet. If a step does not match what you see, stop there, go on in the Browser Lab, and tell us (Contact, at the bottom of this page).
0 of 6 steps done Helper: not connected
What your PC has now
No PC, or stuck? Use the Browser Lab: nothing to install, and every lesson works there.
Part A: Before you install
One small thing first: check that this computer is strong enough.
-
A1 Check my PC (before anything is installed)
First find out whether this Mac can run ROS 2 and Gazebo. The check only reads: it installs nothing, changes nothing and needs no password.
Open the Terminal: press Cmd+Space, type
terminal, and press Return.Press Copy on the line below. Click inside the Terminal, paste with Cmd+V, then press Return.
curl --proto '=https' --tlsv1.2 -fsSL https://www.ros2lab.com/install/check-mac.sh | zsh
Then come back here and press the button.
Your browser may ask "Allow this site to find devices on your local network?". Choose Allow: the page only reads the result from your own computer. Safari cannot do this: use Chrome or Firefox, or paste the result below.
It does not appear? Paste the result instead
Answer by hand, or correct what the check found
What you should see
Terminal ===== ROS2LAB PC CHECK 1 ===== system: mac os: macOS 14.5 ... cores: 8 ram_gb: 8.0 disk_free_gb: 45.2 ... ===== END ===== Now go back to the ROS2Lab page and press "Read the result from my PC".
About 20 lines between two
=====lines (shortened here). After you press the button, a table appears on this page with a green, yellow or red mark for each line.Exactly what it reads, and where the result goes
- The macOS version.
- The processor (Apple silicon or Intel) and its number of cores.
- The size of the memory.
- The free space of your home folder.
- The name of the graphics chip and its Metal level.
- Whether this Mac can run virtual machines.
- Whether UTM is already installed.
- How fast one file downloads from packages.ros.org (up to 8 seconds; the file is thrown away).
The result is printed in your Terminal. It then waits on your own computer (address 127.0.0.1) for up to 10 minutes. This page reads it only when you press the button, and keeps it in this browser. It is not sent to ROS2Lab or anywhere else.
You can read the whole script first: https://www.ros2lab.com/install/check-mac.sh
What these words mean
- Terminal
- A window where you type commands instead of clicking. You type one line and press Enter; the computer answers with text.
- Command
- One line of text that tells the computer to do one thing.
- Script
- A text file with commands. You can open its address in your browser and read every line before you run it.
- 127.0.0.1
- The address that always means "this computer itself". What goes there never leaves your PC.
- Cores
- The workers inside the processor. More cores do more things at the same time.
- Virtual machine
- A computer inside your computer: a program (UTM) that runs Ubuntu in a window on your Mac.
- Graphics card (GPU)
- The part of the PC that draws 3D pictures. Gazebo needs it.
- OpenGL
- The language programs use to ask the graphics card for 3D pictures. Gazebo needs level 3.3 or higher.
- Mbit/s
- How fast your internet is. A bigger number is faster.
Stuck? The 3 most common problems
- The Terminal asks to install "command line developer tools". Press Cancel. This check does not need them. If the window still opens, use "Answer by hand" below.
- The button says it cannot read the result. Safari does not let a web page read from your own Mac. Use "Paste the result" below: select the lines in the Terminal, Cmd+C, then paste here. Chrome and Firefox may ask "Allow this site to find devices on your local network?": allow it.
- I read this guide on my phone. The button only works in a browser on the same Mac. Open "Answer by hand" below and choose what fits your Mac.
None of these? Show this step to your teacher, or to a friend who knows computers. You do not have to wait: every lesson also works in the Browser Lab.
Part B: Get Ubuntu 24.04 in a virtual machine
There are no ROS 2 Jazzy packages for macOS. On a Mac, ROS 2 runs inside Ubuntu, and Ubuntu runs in a window on your Mac with the free program UTM. Your Mac and its files stay as they are. Be honest with yourself about speed: inside a virtual machine, Gazebo's 3D view is slow. If your check shows yellow or red for memory, the Browser Lab will be more pleasant for the Gazebo lessons.
-
B1 Install UTM
UTM is a free program that runs other operating systems in a window.
Open mac.getutm.app, press Download, open the downloaded file, and drag UTM into Applications. Open UTM from Applications.
What you should see
An empty UTM window with a button to create a new virtual machine.
Source: UTM: installation on macOS.
What these words mean
- Virtual machine
- A computer inside your computer: a program (UTM) that runs Ubuntu in a window on your Mac.
Stuck? The 3 most common problems
- macOS says UTM cannot be opened. Open it once with a right-click on UTM in Applications and Open.
- My macOS is older than 12. UTM needs macOS 12 or newer. Update macOS, or use the Browser Lab.
- I already use Parallels or VMware Fusion. They work too: make an Ubuntu 24.04 machine there and go to step B5. This guide only describes UTM.
None of these? Show this step to your teacher, or to a friend who knows computers. You do not have to wait: every lesson also works in the Browser Lab.
-
B2 Download Ubuntu 24.04
You need the Ubuntu 24.04 installer file that fits your Mac's processor. Your PC check shows which one you have.
- Apple silicon (M-series): open cdimage.ubuntu.com/releases/24.04/release and download the file whose name ends in
desktop-arm64.iso. - Intel Mac: open releases.ubuntu.com/24.04 and download the file whose name ends in
desktop-amd64.iso.
Laptop: plug in the charger, and do not close the lid while this runs. If the laptop went to sleep and the step stopped with an error, paste the line again: it goes on where it stopped.
What you should see
One file ending in
.isoin your Downloads folder.Source: Ubuntu 24.04 images (checked 16 Nov 2026: desktop-arm64 and desktop-amd64 are listed).
What these words mean
- ISO file
- One big file that holds a whole operating system, ready to install.
- Ubuntu 24.04
- A free operating system (like Windows or macOS). ROS 2 Jazzy is made for it.
Stuck? The 3 most common problems
- Which Mac do I have? Click the Apple menu › About This Mac. "Chip: Apple M…" is Apple silicon. "Processor: … Intel …" is Intel.
- The download stops halfway. Start it again; most browsers go on where they stopped. Use Wi-Fi, not mobile data.
- There are many files on that page. Take only the one with desktop in its name and the right ending. You do not need the "live-server" ones.
None of these? Show this step to your teacher, or to a friend who knows computers. You do not have to wait: every lesson also works in the Browser Lab.
- Apple silicon (M-series): open cdimage.ubuntu.com/releases/24.04/release and download the file whose name ends in
-
B3 Create the virtual machine
Tell UTM how big the Ubuntu computer should be. Give it about half of your Mac.
- In UTM press Create a New Virtual Machine, then Virtualize, then Linux. If you see a box Use Apple Virtualization, leave it unticked (UTM's guide to 3D graphics in Linux is written for the other mode).
- At Boot ISO Image press Browse and choose the
.isofile from B2. - Memory: 2048 MB (very slow: prefer the Browser Lab)4096 MB (your Mac has 8 GB)8192 MB. CPU cores: half of the cores your PC check shows.
- If this window of UTM has a box for hardware OpenGL acceleration, tick it.
- Storage: 64 GB if your check showed 70 GB free or more; otherwise 40 GB.
- Go on to the summary, name it
Ubuntu ROS 2, and press Save.
What you should see
The new machine is listed at the left of the UTM window, with a large play button.
Source: UTM guide: Ubuntu; UTM: Linux guest support (graphics acceleration is experimental).
What these words mean
- Virtual machine
- A computer inside your computer: a program (UTM) that runs Ubuntu in a window on your Mac.
- OpenGL
- The language programs use to ask the graphics card for 3D pictures. Gazebo needs level 3.3 or higher.
Stuck? The 3 most common problems
- UTM asks "Virtualize" or "Emulate". Always Virtualize. Emulate is many times slower.
- I have only 8 GB of memory. Give Ubuntu 4096 MB and close other apps while you use it. Gazebo will be slow: use the Browser Lab for the Gazebo lessons.
- My disk does not have 64 GB free. Use 40 GB. Under that, the install will not fit: use the Browser Lab. After step B4 you can delete the
.isofile from Downloads; that gives back 3 to 6 GB.
None of these? Show this step to your teacher, or to a friend who knows computers. You do not have to wait: every lesson also works in the Browser Lab.
-
B4 Install Ubuntu in the virtual machine
Start the machine and let Ubuntu's own installer work.
- Press the play button. Choose Try or Install Ubuntu.
- Follow the installer: your language, your keyboard, Install Ubuntu, Erase disk and install Ubuntu. (This "disk" is only the file of the virtual machine, not your Mac's disk.) Ubuntu's own guide shows a picture of every screen: Install Ubuntu Desktop.
- Make a username and a password. Write the password down.
- When it is finished, it asks to restart. First eject the installer: in the UTM window's toolbar open the CD/DVD menu and choose Clear. Then restart.
What you should see
The Ubuntu desktop: a coloured background, a bar of icons at the left, and your name on the login screen.
Source: Ubuntu: Install Ubuntu Desktop; UTM guide: Ubuntu.
What these words mean
- Ubuntu 24.04
- A free operating system (like Windows or macOS). ROS 2 Jazzy is made for it.
Stuck? The 3 most common problems
- After the restart the installer starts again. The installer file is still inserted. Stop the machine, clear the CD/DVD drive in UTM, and start it again.
- The screen stays black after the install. Stop the machine. In its settings in UTM, under Display, choose another display card (one without "GL" in its name), and start again. Gazebo will then use software drawing.
- The mouse is caught inside the window. Press Control+Option to get it back.
None of these? Show this step to your teacher, or to a friend who knows computers. You do not have to wait: every lesson also works in the Browser Lab.
-
B5 Go on inside Ubuntu
From here on you work inside Ubuntu. The helper and this page must be on the same computer, so open the guide in the browser inside the virtual machine.
In Ubuntu, open Firefox (the orange icon in the bar at the left) and type this address:
www.ros2lab.com/setup/ubuntu
There, start with Check my PC again: this time it measures the virtual machine.
Type the address inside Ubuntu. A link pressed here would open on your Mac, not in Ubuntu.
What you should see
The page "Set up ROS 2 on Ubuntu 24.04", inside the Ubuntu window.
Stuck? The 3 most common problems
- Firefox in Ubuntu has no internet. In UTM, the machine's network must be Shared Network (its default). Stop the machine, check its settings, start again.
- Copy and paste between the Mac and Ubuntu does not work. That is why you open this guide inside Ubuntu: then you copy and paste inside one computer.
- Everything inside the window is tiny or slow. In Ubuntu open Settings › Displays and choose a smaller resolution, for example 1280 × 800.
None of these? Show this step to your teacher, or to a friend who knows computers. You do not have to wait: every lesson also works in the Browser Lab.