1. 项目概述与背景如果你正在自动驾驶、机器人仿真或者计算机视觉领域折腾那么Carla这个名字对你来说一定不陌生。它是一个基于Unreal Engine 4构建的开源自动驾驶仿真器提供了海量的传感器模型、逼真的城市环境以及灵活的Python API是算法验证和系统测试的利器。然而Carla的安装过程尤其是特定版本的安装堪称一场“渡劫”。官方文档虽然详尽但面对不同系统环境、依赖版本冲突和网络问题新手和老手都可能栽跟头。今天我就以Ubuntu 20.04 LTS系统上安装Carla 0.9.15这个经典组合为例带你走一遍完整的安装流程并分享我踩过的所有坑和对应的填坑方案。这不仅仅是一个安装命令的罗列更是一次从系统准备到最终验证的深度实战。选择Ubuntu 20.04和Carla 0.9.15是有原因的。Ubuntu 20.04 LTS是一个长期支持版本系统稳定社区支持完善是很多机器人、AI开发者的首选桌面或服务器系统。Carla 0.9.15则是一个功能相对成熟且稳定的版本它修复了早期版本的一些关键bugAPI也趋于稳定同时其资源占用和对硬件的要求相比最新版本如0.9.14要友好一些非常适合在个人工作站或实验室服务器上进行研究和开发。这个组合经过了大量项目的验证生态兼容性好相关的教程和问题解决方案也最丰富。整个安装过程可以分解为几个核心阶段首先是系统环境的准备包括显卡驱动、Docker等基础软件的安装与配置其次是Carla服务器端Server的获取与运行然后是Python客户端Client所需依赖库的安装最后是连接测试与一个简单的示例运行。每个阶段都有其技术要点和潜在的陷阱我会逐一拆解。我的目标是你跟着这篇指南操作下来不仅能成功跑起Carla更能理解每一步背后的原理未来遇到环境变化比如升级系统或Carla版本也能从容应对。2. 系统环境深度准备超越官方清单很多人安装失败第一步就错了。官方文档可能只告诉你需要Ubuntu 16.04/18.04/20.04但没告诉你系统内核、显卡驱动版本、甚至磁盘格式都会产生影响。我们这里做的准备是确保后续所有步骤顺畅的基础。2.1 系统更新与基础工具链首先确保你的系统是最新的。打开终端执行以下命令sudo apt update sudo apt upgrade -y sudo apt autoremove -y这不仅仅是更新软件包列表upgrade会升级所有可升级的包而autoremove会清理那些因为依赖关系改变而不再需要的旧包。一个干净、更新的系统能避免大量因库文件版本过旧导致的编译错误。接下来安装编译Carla Python API客户端和一些依赖所必需的基础开发工具sudo apt install -y build-essential cmake git wget curl software-properties-common lsb-releasebuild-essential: 包含了GCC/G编译器、make等核心编译工具。cmake: 跨平台的安装编译工具很多C项目包括Carla的部分依赖用它来管理构建过程。git: 版本控制工具用于克隆代码仓库。wgetcurl: 命令行下载工具。software-properties-commonlsb-release: 用于管理PPA个人软件包存档和获取系统发行版信息方便后续添加一些第三方软件源。2.2 显卡驱动NVIDIA用户的必由之路Carla的渲染严重依赖GPU因此NVIDIA显卡驱动是必须正确安装的。Ubuntu 20.04自带的nouveau开源驱动无法满足Carla的性能需求。安装专有驱动有多种方法这里推荐使用ubuntu-drivers工具它能自动检测并推荐适合你显卡的驱动版本。首先添加官方的Graphics Drivers PPA以获取最新的驱动版本sudo add-apt-repository ppa:graphics-drivers/ppa -y sudo apt update然后查看可用的驱动推荐ubuntu-drivers devices你会看到类似下面的输出其中recommended标识的就是系统推荐安装的驱动版本例如nvidia-driver-550。 /sys/devices/pci0000:00/0000:00:01.0/0000:01:00.0 modalias : pci:v000010DEd00002504sv00001043sd000087ABbc03sc00i00 vendor : NVIDIA Corporation model : GA106 [GeForce RTX 3060 Lite Hash Rate] driver : nvidia-driver-470-server - distro non-free driver : nvidia-driver-470 - distro non-free driver : nvidia-driver-535 - third-party free driver : nvidia-driver-535-server - distro non-free driver : nvidia-driver-550 - third-party free recommended driver : nvidia-driver-550-server - distro non-free driver : xserver-xorg-video-nouveau - distro free builtin根据推荐安装驱动例如sudo apt install -y nvidia-driver-550安装完成后必须重启系统以使驱动生效。sudo reboot重启后在终端输入nvidia-smi。如果能看到显卡信息、驱动版本和CUDA版本即使显示的是Not Found只要驱动信息正常就行说明驱动安装成功。Carla 0.9.15对CUDA有要求但主要是用于其深度学习相关的功能基础仿真运行不强制要求单独安装CUDA Toolkit因为NVIDIA驱动已经包含了运行CUDA程序所需的基本运行时库。注意如果你使用的是非常新的显卡例如RTX 40系列可能需要安装更高版本的驱动如545、550。务必通过ubuntu-drivers devices确认推荐版本。驱动版本不匹配可能导致Carla无法启动或渲染异常。2.3 Docker引擎的安装与配置从Carla 0.9.12开始官方强烈推荐使用Docker来运行Carla服务器。这带来了环境隔离、依赖统一、部署方便等诸多好处。我们需要在Ubuntu上安装Docker Engine。首先卸载可能存在的旧版本sudo apt remove docker docker-engine docker.io containerd runc添加Docker的官方GPG密钥和软件源curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo \ deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null安装Docker引擎sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin安装完成后将当前用户添加到docker组这样就不需要每次都用sudo来运行docker命令了sudo usermod -aG docker $USER这个改动需要重新登录注销再登录或者打开一个新的终端标签页才能生效。验证Docker安装docker --version docker run hello-world如果能看到Docker版本信息以及Hello from Docker!的提示说明Docker安装并运行正常。2.4 Python环境搭建虚拟环境是王道Carla的Python客户端API对Python版本和第三方库有特定要求。为了避免污染系统Python环境以及不同项目间的依赖冲突使用虚拟环境是绝对的最佳实践。我们将使用conda来管理环境它比venv在科学计算领域更流行包管理也更强大。首先下载并安装Miniconda一个轻量级的conda发行版wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh bash miniconda.sh -b -p $HOME/miniconda安装完成后初始化conda这样每次打开终端conda环境会自动激活base环境$HOME/miniconda/bin/conda init bash关闭当前终端重新打开一个新的终端。你会发现命令行前面多了(base)字样。现在我们为Carla创建一个独立的虚拟环境并指定Python版本为3.7这是Carla 0.9.15官方测试兼容的版本conda create -n carla python3.7 -y conda activate carla激活后命令行提示符会变成(carla)。后续所有Python相关的操作都在这个环境下进行。3. Carla 0.9.15服务器获取与启动Carla服务器是仿真环境的核心它负责运行虚幻引擎渲染场景处理物理计算并通过网络端口提供连接服务。官方提供了预编译的包我们直接下载使用是最方便的方式。3.1 下载与解压发布包在终端中无需在carla虚拟环境下选择一个有足够空间至少20GB的目录下载Carla 0.9.15的发布包。有两个版本可选包含所有素材的完整版约30GB和简化版。对于开发和测试完整版是必须的。# 进入你准备存放Carla的目录例如 ~/Software cd ~/Software # 下载Carla 0.9.15 Linux版本 wget https://carla-releases.s3.eu-west-3.amazonaws.com/Linux/CARLA_0.9.15.tar.gz下载完成后解压文件tar -xzvf CARLA_0.9.15.tar.gz解压后会得到一个名为CARLA_0.9.15的目录。进入该目录你会看到如下关键文件和文件夹CarlaUE4.sh: 用于非Docker方式启动服务器的脚本不推荐。ImportAssets.sh: 用于导入额外资源的脚本。PythonAPI/: 包含Python客户端库和示例。Dockerfile: 用于构建Carla Docker镜像的定义文件。3.2 使用Docker运行Carla服务器官方推荐使用Docker因为它封装了所有复杂的依赖。我们不需要自己构建镜像可以直接使用Carla团队在Docker Hub上维护的镜像。首先拉取对应版本的Carla镜像。标签0.9.15指代版本。docker pull carlasim/carla:0.9.15这个过程会下载几个GB的镜像取决于你的网速请耐心等待。镜像拉取完成后就可以运行Carla服务器了。最基础的运行命令如下docker run -it --rm --nethost --gpus all carlasim/carla:0.9.15 /bin/bash ./CarlaUE4.sh -opengl让我解释一下这个命令的关键参数-it: 交互模式分配一个伪终端。--rm: 容器停止后自动删除容器文件层避免积累垃圾容器。--nethost: 使用主机网络模式。这是最重要的一步。Carla服务器默认在端口2000世界端口和2001RPC端口监听。使用host模式可以让容器内的服务直接使用主机的网络栈这样你的Python客户端运行在主机上才能直接通过localhost:2000连接到服务器。如果使用默认的桥接网络你需要做复杂的端口映射。--gpus all: 将主机的所有GPU资源暴露给容器这是Carla进行GPU渲染所必需的。carlasim/carla:0.9.15: 指定使用的镜像。/bin/bash ./CarlaUE4.sh -opengl: 在容器内执行的命令。-opengl参数指定使用OpenGL渲染后端。对于大多数Linux系统这比默认的Vulkan后端兼容性更好尤其是对于NVIDIA显卡。执行命令后你会看到Unreal Engine的启动日志在终端滚动最终会出现LogCarla: Warning: Waiting for the client to connect...这样的信息这表示Carla服务器已经启动完毕正在等待客户端连接。此时你应该能看到一个Carla的仿真窗口弹出来。不要关闭这个终端窗口它保持着服务器的运行。3.3 无头模式与渲染质量调整有时你不需要图形界面只想在后台运行服务器进行数据生成或测试例如在无显示器的服务器上。这时可以使用-RenderOffScreen参数开启无头模式。docker run -it --rm --nethost --gpus all carlasim/carla:0.9.15 /bin/bash ./CarlaUE4.sh -opengl -RenderOffScreen在无头模式下服务器不会弹出窗口但仿真照常进行客户端可以正常连接。另外你可以通过-quality-level参数调整渲染质量以平衡性能与视觉效果。可选值有Low,Epic等。对于初次测试或性能较弱的机器使用Low可以大幅提升帧率。docker run -it --rm --nethost --gpus all carlasim/carla:0.9.15 /bin/bash ./CarlaUE4.sh -opengl -quality-levelLow4. Python客户端API安装与配置服务器跑起来了我们需要在本地安装Python客户端库才能编写脚本控制仿真中的车辆、获取传感器数据等。4.1 安装Carla Python包之前我们创建的carla虚拟环境现在派上用场了。确保你已经激活了它 (conda activate carla)。Carla的Python客户端库以.egg文件的形式提供。我们需要使用pip来安装它。首先导航到之前解压的Carla目录下的PythonAPI文件夹找到对应你Python版本的.egg文件。由于我们使用的是Python 3.7应该选择carla-0.9.15-py3.7-linux-x86_64.egg对于64位系统。安装命令如下请将路径替换为你自己的实际路径# 假设Carla解压在 ~/Software/CARLA_0.9.15 cd ~/Software/CARLA_0.9.15/PythonAPI pip install carla-0.9.15-py3.7-linux-x86_64.eggpip会处理这个egg文件将其安装到当前虚拟环境的site-packages目录中。安装完成后你可以在Python中import carla了。4.2 安装额外依赖Carla的示例脚本和一些工具依赖其他Python库最核心的是pygame用于创建显示窗口和numpy用于数据处理。在carla虚拟环境中安装它们pip install pygame numpy如果你计划进行图像处理或机器学习可能还需要安装opencv-python,pillow,scikit-image等可以根据需要后续添加。4.3 环境变量设置可选但推荐为了方便我们可以将Carla的PythonAPI路径添加到系统的PYTHONPATH环境变量中。这样无论你在哪个目录下运行Python脚本都能直接import carla并且可以方便地引用示例代码。编辑你的shell配置文件例如~/.bashrc或~/.zshrc在末尾添加export CARLA_ROOT~/Software/CARLA_0.9.15 export PYTHONPATH$PYTHONPATH:${CARLA_ROOT}/PythonAPI/carla/dist/carla-0.9.15-py3.7-linux-x86_64.egg:${CARLA_ROOT}/PythonAPI/carla/agents:${CARLA_ROOT}/PythonAPI/carlaCARLA_ROOT: 指向你的Carla安装根目录。PYTHONPATH: 添加了三个路径egg文件路径确保import carla能成功。agents路径包含一些自动驾驶智能体的代码。carla API源码路径包含一些工具模块。保存文件后执行source ~/.bashrc或source ~/.zshrc使改动生效。之后在任何终端中激活carla虚拟环境后Python都能找到正确的Carla模块。5. 连接测试与基础示例运行现在万事俱备只欠测试。我们将运行一个最简单的官方示例验证服务器和客户端能否正常通信。5.1 手动连接测试首先确保Carla Docker容器正在运行终端里有等待连接的日志。然后打开一个新的终端窗口激活carla虚拟环境conda activate carla启动Python交互式环境python在Python交互界面中输入以下代码import carla import random # 1. 连接到服务器 client carla.Client(localhost, 2000) client.set_timeout(10.0) # 设置连接超时时间 # 2. 获取世界对象 world client.get_world() # 3. 获取蓝图库 blueprint_library world.get_blueprint_library() # 4. 找一辆车的蓝图比如Audi TT vehicle_bp blueprint_library.filter(tt)[0] # 5. 获取所有出生点随机选一个 spawn_points world.get_map().get_spawn_points() spawn_point random.choice(spawn_points) # 6. 尝试生成车辆 try: vehicle world.spawn_actor(vehicle_bp, spawn_point) print(f成功生成车辆: {vehicle.type_id} 在位置 {spawn_point.location}) except Exception as e: print(f生成车辆失败: {e}) # 7. 断开连接可选脚本结束会自动断开 # client.disconnect()如果一切正常你会看到终端打印出类似成功生成车辆: vehicle.audi.tt 在位置 (x, y, z)的信息并且在Carla服务器的仿真窗口中你应该能看到一辆奥迪TT出现在城市的某个位置。这个简单的测试验证了网络连接正常客户端能连接到服务器的2000端口。Python客户端库安装正确。基本的API调用获取世界、蓝图、生成演员工作正常。5.2 运行官方示例脚本Carla提供了丰富的示例脚本位于PythonAPI/examples目录下。我们来运行一个经典的manual_control.py这是一个手动控制车辆的脚本它集成了键盘控制、传感器显示摄像头、激光雷达点云等功能是一个功能完备的测试。在新终端确保在carla虚拟环境且设置了PYTHONPATH中导航到示例目录并运行cd ~/Software/CARLA_0.9.15/PythonAPI/examples python manual_control.py如果运行成功会弹出一个Pygame窗口显示车辆前方的摄像头视图并在终端中显示控制说明WASD控制方向空格刹车等。你可以用键盘控制车辆在城市中行驶同时观察激光雷达点云在另一个窗口中的显示。常见问题与解决错误ModuleNotFoundError: No module named carla说明Python找不到carla模块。请确认1) 是否在carla虚拟环境中2) 是否成功执行了pip install ...egg命令3) 如果没设置PYTHONPATH需要在PythonAPI/examples目录下运行脚本或者将.egg文件路径临时添加到环境变量。错误timeout: error: [Errno 111] Connection refused说明客户端无法连接到服务器。请确认1) Carla Docker容器是否正在运行检查第一个终端2) Docker命令是否使用了--nethost参数3) 防火墙是否阻止了本地2000/2001端口Ubuntu默认通常不会。Pygame窗口黑屏或车辆不渲染可能是渲染问题。尝试在启动服务器时使用-opengl参数我们已经用了。也可能是显卡驱动问题请再次用nvidia-smi确认驱动正常运行并且Docker命令中包含了--gpus all。6. 进阶配置与性能优化成功运行基础示例后你可能需要根据项目需求进行一些进阶配置。6.1 使用自定义地图Carla默认加载的是Town10地图。你可以通过启动参数加载其他地图。首先在Carla根目录的/Game/Carla/Maps/下可以看到所有可用的地图文件.umap和.xodr。在Docker启动命令中通过/Game/Carla/Maps/地图名来指定。docker run -it --rm --nethost --gpus all carlasim/carla:0.9.15 /bin/bash ./CarlaUE4.sh -opengl /Game/Carla/Maps/Town016.2 调整服务器参数以获得更高性能对于资源有限的机器可以通过调整启动参数来提升性能或减少内存占用-quality-levelLow: 如前所述降低渲染质量。-carla-server -fps10: 限制服务器帧率为10 FPS。对于非实时性要求高的算法测试降低帧率可以显著降低CPU/GPU负载。-carla-streaming-port0: 禁用流式传输端口可以减少一些网络开销。 一个综合的性能优化启动命令可能如下docker run -it --rm --nethost --gpus all carlasim/carla:0.9.15 /bin/bash ./CarlaUE4.sh -opengl -quality-levelLow -carla-server -fps206.3 同步模式与固定时间步长默认情况下Carla运行在异步模式下服务器以尽可能快的速度运行客户端需要自己处理时间同步。对于需要严格可控仿真的场景如强化学习应该使用同步模式。在Python客户端中你可以这样设置# 在创建client和world之后 settings world.get_settings() settings.synchronous_mode True # 启用同步模式 settings.fixed_delta_seconds 0.05 # 设置固定时间步长例如0.05秒20Hz world.apply_settings(settings) # 在同步模式下世界的每一次tick都需要由客户端触发 while True: world.tick() # 这会阻塞直到服务器完成这一帧的仿真在同步模式下服务器会等待客户端的world.tick()指令才推进到下一帧从而实现了客户端对仿真节奏的完全控制。这对于数据采集的同步性至关重要。6.4 多客户端连接与交通管理一个Carla服务器可以同时接受多个客户端连接。你可以运行多个Python脚本分别控制不同的车辆或执行不同的任务例如一个脚本控制主车另一个脚本运行交通流生成器。Carla内置了交通管理器Traffic Manager可以模拟复杂的交通流。启用方法如下traffic_manager client.get_trafficmanager() # 获取交通管理器实例 traffic_manager.set_synchronous_mode(True) # 设置交通管理器为同步模式如果世界是同步的 # 设置全局车辆密度、速度偏差等 traffic_manager.set_global_distance_to_leading_vehicle(2.5) traffic_manager.global_percentage_speed_difference(30.0) # 所有车辆比限速慢30%然后你可以通过蓝图生成一些NPC车辆并让交通管理器接管它们for i in range(50): vehicle_bp random.choice(blueprint_library.filter(vehicle.*)) spawn_point random.choice(spawn_points) npc world.try_spawn_actor(vehicle_bp, spawn_point) if npc: npc.set_autopilot(True, traffic_manager.get_port()) # 关键交由交通管理器控制7. 故障排查与常见问题汇总即便按照指南操作由于硬件、网络或系统状态的差异你仍可能遇到一些问题。这里汇总了一些高频问题及其解决方案。7.1 Docker容器启动失败或立即退出现象运行docker run命令后容器日志一闪而过然后容器就退出了。可能原因1NVIDIA容器工具包未安装。Docker需要nvidia-container-toolkit来支持GPU透传。解决安装并配置它。distribution$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt update sudo apt install -y nvidia-container-toolkit sudo systemctl restart docker可能原因2端口冲突。可能已有其他程序占用了2000或2001端口。解决检查端口占用sudo lsof -i :2000或sudo netstat -tulpn | grep :2000终止占用进程或修改Carla服务器的启动端口通过-carla-world-port和-carla-rpc-port参数。7.2 服务器启动后客户端连接超时现象服务器日志显示等待连接但Python客户端报连接超时 (timeout) 或拒绝连接 (Connection refused)。可能原因1Docker网络模式错误。没有使用--nethost或者主机防火墙阻止了连接。解决确保Docker命令包含--nethost。对于防火墙Ubuntu 20.04默认的ufw可能是关闭的。如果开启了需要允许相关端口sudo ufw allow 2000/tcp和sudo ufw allow 2001/tcp。可能原因2客户端连接地址错误。如果服务器运行在另一台机器上需要将localhost替换为那台机器的IP地址。可能原因3服务器尚未完全启动。Unreal Engine加载地图需要时间尤其是第一次运行。请等待终端日志出现LogCarla: Warning: Waiting for the client to connect...再尝试连接。7.3 运行示例脚本时出现Pygame或OpenGL错误现象运行manual_control.py时Pygame窗口无法打开或打开后黑屏终端报错涉及pygame或OpenGL。可能原因1缺少显示环境。如果你是通过SSH连接到无图形界面的服务器或者使用了-RenderOffScreen模式那么需要设置虚拟显示。解决安装xvfb(X虚拟帧缓冲) 并在其中运行脚本。sudo apt install -y xvfb xvfb-run --auto-servernum --server-args-screen 0 1024x768x24 python manual_control.py注意这只能让脚本运行不报错但你将看不到图像。对于需要查看图像的情况你需要配置X11转发对于SSH或者在有显示器的机器上运行。可能原因2Pygame版本或依赖问题。解决尝试升级或重装Pygame及其依赖。pip install --upgrade pygame sudo apt install -y libsdl2-2.0-0 libsdl2-image-2.0-0 libsdl2-ttf-2.0-0 libsdl2-mixer-2.0-07.4 生成车辆或传感器时崩溃现象在调用spawn_actor生成车辆或传感器时客户端或服务器崩溃。可能原因1出生点冲突。尝试在同一个位置生成两个演员。解决使用try_spawn_actor代替spawn_actor它不会抛出异常而是返回None。或者在生成前检查出生点是否被占用。可能原因2蓝图属性设置错误。例如为传感器设置了无效的属性值。解决仔细检查蓝图属性的名称和取值范围。可以通过blueprint.get_attribute_names()和blueprint.get_attribute(‘attrib_name’).recommended_values来查看。7.5 内存不足与系统优化Carla是一个资源消耗大户尤其是内存。Town10地图加载后服务器进程可能占用超过8GB的RAM。如果你的系统内存较小例如16GB在运行Carla服务器、Python客户端以及可能的数据处理程序时可能会遇到内存不足OOM导致系统卡顿或进程被杀死。优化建议1关闭不必要的图形效果。使用-quality-levelLow启动服务器。优化建议2使用更小的地图。例如Town01或Town02它们对内存的需求更低。优化建议3增加系统交换空间Swap。这可以作为内存的缓冲防止系统直接崩溃。# 检查当前swap大小 sudo swapon --show # 如果很小或没有可以创建一个4GB的swap文件 sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile # 永久生效编辑 /etc/fstab添加一行/swapfile none swap sw 0 0优化建议4监控资源使用。使用htop,nvidia-smi,docker stats等工具实时监控CPU、内存、GPU使用情况及时发现问题进程。整个安装和配置过程确实涉及多个环节但每一步都有其明确的目的。从系统准备到最终验证我试图不仅给出命令更解释其背后的逻辑。这样当你在未来升级Carla版本、更换Ubuntu系统或者遇到本文未覆盖的奇怪错误时你拥有的将不仅仅是操作步骤而是解决问题的底层思路和排查能力。记住仿真环境的搭建是自动驾驶研发的第一步一个稳定、高效的Carla环境能为后续的算法开发节省大量时间。如果在实践中遇到新的问题多查阅Carla的官方文档和GitHub Issues那里是解决问题最宝贵的资源库。