ROS2 - Instalação do ambiente

ROS2 - Instalação do ambiente

Introdução

O objetivo desta aula é guiá-lo na instalação do Robot Operating System (ROS) em sua máquina. O resultado final desta aula é habilitar o comando ros2 em sua máquina e ter a variável de ambiente ROS_DISTRO igual a lyrical. Ao concluir, você deverá ser capaz de:
  • escolher e executar uma das trilhas de instalação (Ubuntu nativo, Docker ou WSL2);
  • carregar o ambiente do ROS 2 em um terminal (source);
  • verificar a instalação com os exemplos talker, listener e turtlesim;
  • gerar o comprovante (print) exigido para a Aula 1.

Escolha uma trilha

O caminho ideal é utilizar o Linux (preferencialmente o Ubuntu 26.04 ou o RHEL) como sistema operacional em seu notebook. Para usuários Windows, saiba que é possível implementar dual-boot em sua máquina, o que permite inicializar o computador no Windows ou no Linux a cada boot. Para aqueles que não desejam/podem seguir por este caminho, será demonstrado como configurar o ROS através do Docker ou, no Windows, do WSL2.
Assim, escolha uma das trilhas a seguir. A Trilha A (Ubuntu nativo) dá melhor desempenho e menos problemas com a interface gráfica e integração com o CoppeliaSim. A Trilha B (Docker) evita mexer no seu sistema e funciona em Windows, macOS e Linux. A Trilha C (WSL2) instala o Ubuntu 26.04 dentro do Windows, sem particionar o disco, e é a opção mais simples para quem usa Windows.
Trilha A: Ubuntu 26.04 nativoTrilha B: DockerTrilha C: Windows com WSL2
Mexe no seu sistema?Sim (particiona o disco)NãoPouco (habilita o WSL2 no Windows)
DesempenhoMelhorBomBom
Interface gráfica (turtlesim, rqt)DiretaExige configuraçãoDireta (WSLg)
Funciona emPC com espaço em disco livreWindows (WSL2), macOS, LinuxWindows 10 e 11
DificuldadeMaior na instalaçãoMaior na interface gráficaMenor
Dica
Em dúvida? Se o seu computador tem espaço livre e você já usa (ou quer usar) Linux, prefira a Trilha A. Se não quer particionar o disco, prefira a Trilha C (Windows) ou a Trilha B (macOS).

Trilha A — Ubuntu 26.04 nativo

Instalando o Ubuntu em dual-boot

Esta seção resume o processo de instalação do Ubuntu 26.04 LTS ao lado do Windows. Os detalhes variam conforme o fabricante do seu computador, então use-a como roteiro e consulte o manual do equipamento quando necessário . Os passos são:
  1. Faça backup dos arquivos importantes antes de qualquer particionamento.
  2. Reserve espaço em disco: no mínimo cerca de 50 GB para o Ubuntu; se pretende continuar usando o ROS depois do módulo, prefira 80 GB ou mais.
  3. Prepare o Windows: desative o BitLocker (ou a criptografia de dispositivo), se estiver ativo, antes de reduzir a partição; desative a "inicialização rápida" (Fast Startup); e reduza a partição pelo Gerenciamento de Disco.
  4. Baixe o Ubuntu 26.04.1 LTS do site oficial da Canonical. Atente-se em baixar a versão Desktop e adequada ao processador de sua máquina (i.e., amd64 ou arm64).

    Download Ubuntu Desktop

  5. Crie o pen drive de instalação: baixe a ISO do Ubuntu 26.04 LTS em ubuntu.com e grave-a com o Rufus (Windows) ou com o balenaEtcher.
  6. Inicie pelo pen drive: a tecla de acesso ao menu de boot varia (F12, F10, Esc, F2...). Escolha a opção de instalar ao lado do Windows (Install alongside Windows).
  7. Pós-instalação: atualize o sistema com os comandos abaixo.
bash
sudo apt update && sudo apt upgrade
Perigo
Particionar o disco envolve risco de perda de dados. Faça o backup antes e, se não se sentir seguro, procure o professor antes de realizar qualquer ação irreversível.
Atenção
Se o seu computador usa Secure Boot com drivers proprietários (por exemplo, placas NVIDIA), pode haver passos adicionais. Procure o professor antes de arriscar a instalação.
Nota
Alternativa sem particionar: instalar o Ubuntu em uma máquina virtual. Funciona, mas a interface gráfica e o desempenho dependem da configuração da VM.

Instalando o ROS 2 Lyrical

Com o Ubuntu 26.04 instalado e atualizado, instalaremos o ROS 2 por pacotes .deb, seguindo o guia oficial da Lyrical . A sequência (configurar o locale, habilitar os repositórios, instalar e carregar o ambiente) é a mesma descrita nos livros-texto do módulo, mudando apenas a distribuição .
Abra um terminal e execute, em ordem, os blocos a seguir. Primeiro, garanta um locale com suporte a UTF-8:
bash
locale   # deve mostrar UTF-8
sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8
locale   # confira novamente
Em seguida, habilite o repositório Universe do Ubuntu:
bash
sudo apt install software-properties-common
sudo add-apt-repository universe
Agora instale o pacote ros2-apt-source, que fornece as chaves e a configuração do repositório do ROS 2:
bash
sudo apt update && sudo apt install curl -y
export ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F'"' '{print $4}')
curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}})_all.deb"
sudo dpkg -i /tmp/ros2-apt-source.deb
Atenção
Os comandos do bloco acima são longos e podem mudar entre versões da documentação. Se algum falhar, copie a versão atual diretamente do guia oficial da Lyrical, e não de vídeos ou tutoriais antigos (que costumam ser de outras distribuições).
Com o repositório configurado, atualize o sistema e instale o ROS 2 em sua versão desktop (ROS, RViz, demos e tutoriais), além das ferramentas de desenvolvimento (colcon, rosdep, vcstool e outras), que usaremos a partir da Aula 3:
bash
sudo apt update
sudo apt upgrade
sudo apt install ros-lyrical-desktop
sudo apt install ros-dev-tools
Por fim, carregue o ambiente. O primeiro comando vale apenas para o terminal atual; o segundo faz com que todo terminal novo já abra com o ROS 2 carregado:
bash
source /opt/ros/lyrical/setup.bash
echo "source /opt/ros/lyrical/setup.bash" >> ~/.bashrc

Instalando o ROS 2 Lyrical no Ubuntu (guia oficial)

Fonte de referência dos comandos: confira aqui em caso de divergência.

Dica
Depois da instalação, siga para a seção Verificação do ambiente deste módulo, comum às duas trilhas.

Trilha B — Docker

Instalando o Docker

Nesta trilha, o ROS 2 roda dentro de um container: um ambiente isolado, com o Ubuntu e o ROS 2 já instalados, que não altera o seu sistema . O seu código fica em uma pasta do seu computador, fora do container, e sobrevive ao término dele. A instalação do Docker depende do seu sistema operacional:
  • Ubuntu: siga o guia oficial do Docker Engine, configurando o repositório apt do Docker. Em seguida, para não precisar de sudo em todo comando, adicione o seu usuário ao grupo docker, saia e entre novamente na sessão (ou reinicie) e teste.
  • Windows: instale o WSL2 (wsl --install) com uma distribuição Ubuntu e o Docker Desktop com a integração WSL2 habilitada. Aplicações gráficas costumam funcionar via WSLg.
  • macOS: instale o Docker Desktop. A interface gráfica exige o XQuartz, o que é mais trabalhoso: se possível, prefira Linux ou Windows com WSL2.
bash
# Ubuntu: usar docker sem sudo
sudo usermod -aG docker $USER
# saia e entre na sessão novamente (ou reinicie), depois teste:
docker run --rm hello-world

Instalar o Docker Engine no Ubuntu (guia oficial)

Passo a passo da configuração do repositório apt do Docker.

Primeiro contato com a imagem do ROS 2

Para testar o conceito, comece pela imagem mínima (sem interface gráfica). Ela é suficiente para verificar que o ros2 funciona e que a distribuição é a Lyrical:
bash
# imagem mínima (sem interface gráfica)
docker run -it --rm ros:lyrical

# dentro do container:
ros2 --help
printenv ROS_DISTRO   # deve imprimir: lyrical
As imagens oficiais ros:lyrical (variantes core, base e perception) ficam no Docker Hub. As variantes com interface gráfica e simulação (desktop, desktop-full e simulation) ficam no perfil osrf/ros .

Imagens Docker oficiais do ROS

Página da imagem ros no Docker Hub, usada na Trilha B.

Nota
Na data de escrita deste guia (19/10/2026), a imagem mínima ros:lyrical é publicada para amd64 e arm64, mas a osrf/ros:lyrical-desktop-full (com interface gráfica) é publicada apenas para amd64 e tem cerca de 1,9 GB. Se o seu computador usa processador ARM (como os Macs com chip Apple), converse com o professor antes de começar.

Container com interface gráfica

O turtlesim, o rqt e o RViz2 precisam de uma janela gráfica, então usaremos a imagem osrf/ros:lyrical-desktop-full. O comando abaixo, para Linux com X11, libera o acesso do container ao servidor gráfico e o inicia com a sua pasta de trabalho montada:
bash
docker pull osrf/ros:lyrical-desktop-full

# Linux (X11): liberar acesso do container ao servidor gráfico
xhost +local:docker

docker run -it --rm \
  --net=host \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v ~/ros2_ws:/root/ros2_ws \
  osrf/ros:lyrical-desktop-full
Entenda o que cada opção faz:
  • --net=host: facilita a descoberta DDS entre terminais e containers;
  • -e DISPLAY e o volume /tmp/.X11-unix: permitem que as janelas apareçam na sua tela;
  • -v ~/ros2_ws:/root/ros2_ws: o código do aluno vive fora do container, no computador, e sobrevive ao término do container.
Atenção
Ubuntu 26.04 usa Wayland por padrão. O encaminhamento X11 normalmente funciona via XWayland, mas o procedimento deve ser validado em cada máquina. Se a janela do turtlesim não abrir, confira o DISPLAY, o xhost e o socket X11, e procure o instrutor.
Atenção
Arquivos com dono root. Arquivos criados dentro do container podem ficar com dono root no seu computador. Para corrigir, use sudo chown -R $USER:$USER ~/ros2_ws.
Dica
Para abrir um segundo terminal no mesmo container, use docker exec -it nome_do_container bash. É por isso que o Docker Compose, a seguir, com um nome de container fixo, é mais prático.

Docker Compose

O Docker Compose guarda toda a configuração em um arquivo e permite subir e descer o ambiente com um único comando . Crie um arquivo docker-compose.yml em uma pasta de trabalho com o conteúdo abaixo. Troque o ROS_DOMAIN_ID pelo número da sua dupla (o instrutor informará na Aula 1).
yaml
services:
  ros:
    image: osrf/ros:lyrical-desktop-full
    container_name: ros2_lyrical
    network_mode: host
    stdin_open: true
    tty: true
    environment:
      - DISPLAY=${DISPLAY}
      - ROS_DOMAIN_ID=10
      - QT_X11_NO_MITSHM=1
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix
      - ./ros2_ws:/root/ros2_ws
    working_dir: /root/ros2_ws
    command: bash
Para usar:
bash
xhost +local:docker                   # Linux/X11
docker compose up -d
docker exec -it ros2_lyrical bash     # abra quantos terminais quiser
docker compose down
Nota
Também é possível usar um Dev Container no VS Code (extensão Dev Containers), que abre o editor já dentro do container . É opcional e mais confortável para quem já usa o VS Code.

Trilha C — Windows com WSL2

O que é o WSL2

O Windows Subsystem for Linux (WSL2) executa um Ubuntu de verdade dentro do Windows, sem particionar o disco e sem reiniciar o computador a cada troca de sistema. Para o ROS 2, o resultado é um terminal Ubuntu 26.04 onde os comandos da Trilha A funcionam como em uma instalação nativa, e as janelas gráficas (turtlesim, rqt) aparecem direto no desktop do Windows graças ao WSLg.
  • Ubuntu 26.04 rodando dentro do Windows;
  • não particiona o disco;
  • janelas gráficas abrem no desktop do Windows;
  • comandos idênticos aos da Trilha A.

Requisitos

  • Windows 11, ou Windows 10 atualizado;
  • virtualização habilitada na BIOS/UEFI;
  • conta com permissão de administrador;
  • cerca de 15 GB livres no disco.
Nota
Para conferir se a virtualização está ativa, abra o Gerenciador de Tarefas, aba Desempenho, CPU: o campo Virtualização deve aparecer como Habilitado.

Instalando o WSL2 e o Ubuntu 26.04

Os passos desta seção são executados no PowerShell do Windows, não no Ubuntu.
Passo 1 — instalar o WSL. Abra o PowerShell como administrador (botão direito no menu Iniciar) e execute:
powershell
wsl --install
Reinicie o computador se o Windows pedir.
Passo 2 — atualizar o WSL e escolher a distribuição. Depois do reinício, atualize o WSL e confira se o Ubuntu 26.04 aparece na lista:
powershell
wsl --update
wsl --list --online
Passo 3 — instalar o Ubuntu 26.04:
powershell
wsl --install Ubuntu-26.04
Ao terminar, o Ubuntu abre e pede um nome de usuário e uma senha. Eles valem só dentro do Linux e não precisam ser os do Windows.
Passo 4 — conferir a versão. De volta ao PowerShell:
powershell
wsl -l -v
A coluna VERSION da distribuição Ubuntu-26.04 deve mostrar 2.
Dica
O comando wsl --install sem nome de distribuição instala a distribuição padrão, que pode ser outra versão do Ubuntu. Se isso aconteceu, instale a 26.04 como no passo 3 e abra-a com wsl -d Ubuntu-26.04.

Instalando o Ubuntu no WSL2 (documentação oficial)

Fonte de referência dos comandos desta seção.

Preparando o Ubuntu

A partir daqui, use o terminal do Ubuntu (abra o app Ubuntu 26.04 no menu Iniciar ou execute wsl -d Ubuntu-26.04 no PowerShell). Atualize os pacotes e confirme a versão:
bash
sudo apt update && sudo apt upgrade -y
lsb_release -a   # deve mostrar 26.04
Confira também se o systemd está ativo:
bash
systemctl is-system-running   # running ou degraded: ok
Se o comando reclamar que o systemd não está em execução, habilite-o e reinicie o WSL:
bash
cat /etc/wsl.conf   # confira antes se já existe a seção [boot]
printf '[boot]\nsystemd=true\n' | sudo tee -a /etc/wsl.conf
Depois, no PowerShell, execute wsl --shutdown e abra o Ubuntu de novo.

Usando o systemd no WSL (Microsoft)

Detalhes sobre o arquivo /etc/wsl.conf e a opção systemd.

Instalando o ROS 2 Lyrical no WSL

Com o Ubuntu 26.04 pronto, instale o ROS 2 Lyrical exatamente como na Trilha A, seguindo a seção Instalando o ROS 2 Lyrical deste módulo . Execute todos os comandos no terminal do Ubuntu, nunca no PowerShell.
Atenção
Escolha uma trilha. Ter duas instalações do ROS 2 na mesma máquina (por exemplo, WSL2 e Docker) confunde o source e dificulta o suporte.

Interface gráfica com o WSLg

O WSLg já vem com o WSL atualizado, então não é preciso instalar um servidor X. Teste com o turtlesim:
bash
source /opt/ros/lyrical/setup.bash
ros2 run turtlesim turtlesim_node
Uma janela com a tartaruga deve abrir no desktop do Windows. Se não abrir:
  • execute wsl --update no PowerShell;
  • execute wsl --shutdown e abra o Ubuntu de novo;
  • confira se echo $DISPLAY mostra um valor como :0.
Dica
Se o rviz2 abrir em branco ou travar, tente renderização por software: export LIBGL_ALWAYS_SOFTWARE=1 antes de executá-lo.

Boas práticas no WSL

  • crie seus projetos em ~/ros2_ws, dentro do Linux;
  • evite /mnt/c: compilar lá é muito mais lento;
  • para ver arquivos do Linux no Windows, execute explorer.exe . no terminal;
  • para editar, use o VS Code com a extensão WSL e rode code . na pasta do projeto.
Dica
Depois da instalação, siga para a seção Verificação do ambiente deste módulo, comum a todas as trilhas.

Verificação do ambiente

Checklist (ambas as trilhas)

Esta verificação é igual para as duas trilhas e gera o comprovante da pré-aula. Abra três terminais (na Trilha B, os demais terminais são abertos com docker exec) e lembre-se de que todo terminal novo precisa carregar o ambiente com source /opt/ros/lyrical/setup.bash (já feito automaticamente se você adicionou a linha ao ~/.bashrc).
No primeiro terminal, confira a distribuição e liste os pacotes:
bash
printenv ROS_DISTRO                      # esperado: lyrical
ros2 pkg list | head                     # lista de pacotes
Depois, rode o par de demonstração, em terminais separados, e o simulador:
bash
ros2 run demo_nodes_cpp talker           # Terminal 1
ros2 run demo_nodes_py listener          # Terminal 2 (deve receber as mensagens)
ros2 run turtlesim turtlesim_node        # Terminal 3 (abre a janela da tartaruga)
Dica
Critério de aceitação: o talker e o listener trocando mensagens e a janela do turtlesim aberta. Se os dois itens funcionam, sua instalação está pronta.
Exercício 4·O que cada comando prova?
Que parte da instalação cada um dos comandos da verificação confirma? Considere printenv ROS_DISTRO, o par talker/listener e o turtlesim_node.
Pense no que existe só quando cada componente está instalado: o ambiente carregado, a comunicação entre nós e a interface gráfica.
printenv ROS_DISTRO mostra que o ambiente do ROS 2 foi carregado e que a distribuição é a Lyrical. O par talker (C++) e listener (Python) confirma que a comunicação funciona e que as bibliotecas em C++ e em Python estão instaladas. O turtlesim_node confirma que a interface gráfica funciona, o que é essencial para a Aula 2.

Problemas comuns

Consulta rápida

Antes de pedir ajuda, confira se o seu caso está na tabela. Ao escrever no canal de dúvidas, informe a trilha escolhida, o comando executado e a mensagem de erro completa.
SintomaCausa provávelSolução
ros2: command not foundEsqueceu o source /opt/ros/lyrical/setup.bashCarregar o ambiente; adicionar ao ~/.bashrc
colcon: command not foundros-dev-tools não instaladosudo apt install ros-dev-tools
Janela do turtlesim não abre no DockerDISPLAY não repassado, sem xhost ou Wayland/XWaylandxhost +local:docker; conferir -e DISPLAY e o socket X11
Arquivos do workspace com dono rootContainer roda como root com volume montadosudo chown -R $USER:$USER ~/ros2_ws
ModuleNotFoundError: rclpyAmbiente virtual Python ou conda sobrepondo o do sistemaDesativar o venv/conda; usar o Python do sistema
Comando de tutorial ou livro falhaMaterial escrito para a Jazzy (ros-jazzy-*)Trocar jazzy por lyrical e conferir a documentação da Lyrical
wsl --install avisa que a virtualização está desabilitadaVirtualização desligada na BIOS/UEFIAtivar Intel VT-x ou AMD SVM na BIOS/UEFI
Ubuntu-26.04 não aparece em wsl --list --onlineWSL desatualizadowsl --update no PowerShell
Janela do turtlesim não abre no WSLWSLg desatualizadowsl --update e wsl --shutdown, depois abrir o Ubuntu
Compilação muito lenta no WSLProjeto dentro de /mnt/cMover o projeto para ~/ros2_ws
Atenção
Os livros do módulo (ROS 2 from Scratch e Mastering ROS 2) foram escritos para a Jazzy . Ao seguir os exemplos, troque jazzy por lyrical nos pacotes e caminhos, e confira a documentação da Lyrical em caso de dúvida.

Referências

  1. Open Robotics. (2026). ROS 2 Documentation: Lyrical Luth — Installing on Ubuntu. https://docs.ros.org/en/lyrical/Get-Started/Installation/Ubuntu-Install-Debs.html
    https://docs.ros.org/en/lyrical/Get-Started/Installation/Ubuntu-Install-Debs.html
  2. Joseph, L., & Cacace, J. (2025). Mastering ROS 2 for Robotics Programming: design, build, simulate, and prototype complex robots using the Robot Operating System 2 (4th ed.). Packt Publishing.
  3. Open Robotics. (2026). ros — Docker Official Image and osrf/ros. Docker Hub. https://hub.docker.com/_/ros
    https://hub.docker.com/_/ros
  4. Renard, E. (2024). ROS 2 from Scratch. Packt Publishing.

Autor: FILIPE A. S. ROCHA

Publicado em 19 de outubro de 2026· Atualizado em 20 de outubro de 2026