ROS TurtleSim Beginner's Guide (Mac)

In this article I show an absolute beginner to ROS (Robot Operating System) how to run a TurtleSim (turtle robot simulation) as quickly as possible on a Mac. The ROS tutorials are great. But I’ve noticed hobbyists get frustrated with the lengthy setup process.

To simplify the process, I’m going to use Docker and Xquartz to show you how to get a visual simulation working. Then you can go back and better appreciate what the tutorials are trying to accomplish.

How to run ROS turtlesim on a Mac:

  • Install Docker
  • Install Xquartz
  • Setup Xquartz access control
  • Setup a ROS docker image
  • Run roscore in the docker container
  • Run turtlesim in the docker container
  • Control the turtle with the keyboard

This tutorial will be easier for you if you are comfortable with a terminal window command line and installing utilities on a Mac.

Step 1. Install Docker

If you’ve already installed Docker for Mac, move to the next step. If not, follow the install instructions from this link:

Step 2. Install Xquartz

To install Xquartz for a Mac, go to this link and download the *.dmg file:

  • Download the *.dmg file for your operating system
  • Open the *.dmg file and you should see the Xquartz.pkg file
  • Double click the *.pkg file to run the installer
  • Note that it may take a moment and that the installer window might end up behind another window

Once Xquartz is installed you need to run it and set a security preference:

  • Click a blank area on your Mac desktop which will make Finder the focus of the main menu
  • On the main menu select: Go > Applications
  • Expand the Utilities folder
  • Double-click Xquartz to run it
  • In the main menu select: Xquartz > Preferences…
  • Click the Security tab in the dialog box
  • Check Allow connections from network clients
  • Close the dialog box
  • From the main menu select: Xquartz > Quit X11

Step 3: Setup Xquartz access control

The docker images run headless, which means you need to setup Xquartz running on your Mac to display the simulation.

  • Open up a terminal window
  • Run the following at the command line:
xhost +

You should see a response like this: being added to access control list

If you press Command-Tab you will see that Xquartz was launched by the xhost command.

Leave this terminal window running.

Step 4: Setup a ROS docker image

Instead of struggling to get ROS running on your Mac, you can just use an official docker container image (ros).

  • Open up a second terminal (with terminal in focus, press: Command-T)
  • Run the following command:
docker pull ros

This will pull the latest ROS docker image down to your local machine. You don’t have to do this every time.

  • In the same terminal window, run the following command
docker run -e DISPLAY=host.docker.internal:0 -it --name my-ros ros

This will now put you inside the ROS docker container where you can run commands. The DISPLAY environment variable creates a pointer to send display commands to Xquartz.

Within the container run the following to update packages and install the ROS tutorials:

sudo apt-get update
sudo apt-get dist-upgrade
sudo apt-get install ros-melodic-ros-tutorials

The last line refers to the melodic version of ROS.

Step 5: Run roscore in the docker container

If you are familiar with pubsub, or tools like MQTT you probably understand how messaging systems work. If not, don’t worry if you don’t understand the next paragraph.

Behind the scenes roscore runs ROS Master which tracks publisher and subscriber nodes and services. Without going into too much detail for the beginner, running roscore allows nodes to send messages to one another. Without roscore running, the various nodes within ROS can’t talk to each other. So you need to leave it running in the background.

  • Run roscore:

Leave this terminal window running as well.

Step 6: Run turtlesim in the container

Because roscore is running in the foreground, you need to open up another window into the container to run the simulation.

  • Open up a third terminal window (Command-T)
  • Run the following command:
docker ps -l

You should see a list of containers. One of them should list in the last column the name given when you ran / created the last container:

... my-ros
  • In the same window run this command:
docker exec -it my-ros bash

This lets you run in another terminal window within the container. Notice that you are using the name you gave the container (my-ros). That helps docker figure out which container you are referring to.

From within the container run the following:

  1. mkdir -p ~/catkin_ws/src
  2. cd ~/catkin_ws/
  3. source /opt/ros/melodic/setup.bash
  4. catkin_make
  5. source devel/setup.bash
  7. rosrun turtlesim turtlesim_node

If Xquartz is setup properly, you should see an Xwindow running turtlesim pop up.

If not, see the troubleshooting guide near the end of this article. Or make sure it isn’t hiding behind another window.

Step 7: Control the turtle with the keyboard

Because you now have two services running in the foreground (roscore, turtlesim), you need to open up yet another window to run the keyboard controller.

  • Open up yet another terminal window (Command-T):
docker exec -it my-ros bash
  • From within the container, run the following:
cd ~/catkin_ws/
source /opt/ros/melodic/setup.bash
rosrun turtlesim turtle_teleop_key
  • Place the simulator window and the terminal / container window side by side
  • Click the mouse in the last container window you created so that it has focus
  • Use the arrow keys to move the turtle around the screen


I work for a company that makes AMRs (autonomous mobile robots). They assist warehouse and even grocery store employees in managing products. The robots are driven through ROS. If you think you might like to work for a robotics company, it is a technology that you should familiarize yourself with. Even as a hobbyist, you can be assured that the technology is being actively worked on and maintained by a large open source community.

In this article I showed you how to quickly get started running a ROS turtle robot simulation on your Mac. By giving you something visual to grasp on to, I hope it made ROS a little less confusing. Hopefully with a new found appreciation for the basics of how ROS works, the tutorials will be easier to comprehend.

Below I’ve added some cleanup, troubleshooting guides and links to help you with any issues that might come up


Here are some cleanup instructions which will help you remove test files or reset your environment to start over.

Exit a container

  • Press Ctrl-C to stop roscore, etc.
  • Press Ctrl-D to exit a container

Remove the ROS container:

docker stop my-ros
docker rm my-ros

You can recreate it later by running the docker run command again.

Remove the ROS image:

If you would also like to remove the docker ros image:

docker rmi ros


Here are some common problems that you may run into.

Could not connect to any X display

If you see this error:

QStandardPaths: XDG_RUNTIME_DIR not set, defaulting to '/tmp/runtime-root'
qt.qpa.screen: QXcbConnection: Could not connect to display host.docker.internal:0
Could not connect to any X display

See the step about setting the client connections preferences for Xquartz. You may need to start this tutorial over to get it to work.

After rebooting your machine you may see this when trying to use the container again. See the section below on the restarting sequence to make sure Xquartz can communicate with the container.

The docker run command is giving you an error

If you try to run this command, but get an error that is because the container has already been created.

docker run -e DISPLAY=host.docker.internal:0 -it --name my-ros ros

It’s not very intuitive, but docker run is used to create new containers. So if you try to run it again, you get an error because you are actually trying to create a container that already exists.

Try running this command to reconnect to the existing container:

docker exec -it my-ros bash

If you get an error like this, then the container already exists. But is not running:

Error response from daemon: Container ... is not running

You need to restart it like this:

docker start my-ros

Then you can run the exec command again:

docker exec -it my-ros bash

Running roscore again from an existing container

Xquartz can lose its connection to the container. In that case, you have to restart things in a certain sequence to get it to work again.

  • Shutdown Xquartz: Xquartz > Quit X11
  • Reauthorize the connection to restart Xquartz:
xhost +
  • If the container isn’t running, start it:
docker start my-ros
  • Exec into the container
docker exec -it my-ros bash
  • Setup ROS (in this case using the melodic version):
source /opt/ros/melodic/

Now you should be able to restart roscore:


Restart the simulator

In a new terminal window:

docker exec -it my-ros bash

In the container:

source /opt/ros/melodic/
rosrun turtlesim turtlesim_node

Restart keyboard control

In a new terminal window:

docker exec -it my-ros bash

In the container:

source /opt/ros/melodic/
rosrun turtlesim turtle_teleop_key


  • How to show X11 windows with Docker on Mac [1]

About the Author

Mitch Allen has worked for software companies in Silicon Valley, along Boston’s Route 128 and in New York’s Silicon Alley. He currently works for a robotics company in Massachusetts.