ramalama

环境要求

• Python 3.9 或更高版本（PyPI / Windows 安装方式需要）
• Windows 需配合 Docker Desktop 或 Podman Desktop（WSL2 后端）
• macOS 自包含安装包已内置 Python 及全部依赖，无需额外环境
• 使用 MLX 运行时需 macOS 系统 + Apple Silicon（M1/M2/M3 或更新）硬件
• 需要本机可用的 Podman 或 Docker 容器引擎来运行模型容器

安装与启动步骤

1. 1Fedora 使用 dnf 安装

   在 Fedora 系统上直接通过官方仓库安装，无需 pip，安装后即可使用 ramalama 命令。

   sudo dnf install ramalama

   复制

2. 2PyPI 方式安装

   适用于大多数 Linux 与 macOS 环境，前提是已安装 Python 3.9 或更高版本。

   pip install ramalama

   复制

3. 3一键脚本安装

   Linux 和 macOS 通用，脚本自动完成下载与安装，可省去手动配置 Python 环境。

   curl -fsSL https://ramalama.ai/install.sh | bash

   复制

4. 4macOS 安装包安装

   先从 Releases 页面下载最新的 .pkg 安装包，再执行命令安装；也可直接双击安装包。

   sudo installer -pkg RamaLama-*-macOS-Installer.pkg -target /

   复制

5. 5Windows 安装

   在已装好 Docker Desktop 或 Podman Desktop（WSL2 后端）的 Windows 上，用 PowerShell 通过 pip 安装。

   pip install ramalama

   复制

6. 6安装 MLX 运行时

   仅 macOS + Apple Silicon 需要，MLX 以 uv 工具形式装在宿主机上，且只能配合 --nocontainer 使用。

   uv tool install mlx-lm

   复制

7. 7验证安装

   执行 info 子命令查看 RamaLama 的配置信息，确认加速器、容器引擎与推理引擎被正确识别。

   ramalama info

   复制

关键配置

如何确认成功

运行 ramalama info，能打印出包含 Accelerator、Engine、Image、Inference 等字段的 JSON 配置信息，即表示安装成功。

常见问题

注意事项

• 模型默认在 Podman 或 Docker 的 rootless 容器中运行，模型以只读卷方式挂载，与宿主机隔离。
• ramalama run 会使用 --network=none，容器无法访问网络，避免数据外泄。
• 容器以 --rm 运行，进程退出后容器内写入的内容会被删除。
• Windows 上模型存储优先使用硬链接（无需管理员权限），不支持时回退为文件复制。