containers/ramalama
1
0
Fork 0
mirror of https://github.com/containers/ramalama.git synced 2026-02-05 06:46:39 +01:00
Code Issues Wiki Activity
Files
d80c22ff5b1f47860d1395e7c13feca23449347a
ramalama/docs/MACOS_INSTALL.md
Mike Bonnet c72493f24a macOS installer: build and install an app bundle 
Switch from building a onefile executable to a onedir executable and app bundle.
The onefile executable is less efficient because it needs to extract resources
into a temp directory on every run, and it will no longer be supported as part
of an app bundle in future versions of pyinstaller.

Skip installing config and inference files under /usr, they will be referenced
from within the app bundle.

Use a plist when calling pkgbuild to avoid the macOS installer "relocating"
the app bundle to arbitrary locations, which breaks the "ramalama" symlink.

Signed-off-by: Mike Bonnet <mikeb@redhat.com>
2026-01-13 11:52:31 -08:00

4.7 KiB
Raw Blame History

macOS Installation Guide for RamaLama

This guide covers the different ways to install RamaLama on macOS.

Method 1: Self-Contained Installer Package (Recommended)

The easiest way to install RamaLama on macOS is using our self-contained .pkg installer. This method includes Python and all dependencies, so you don't need to install anything else.

Download and Install

  1. Download the latest installer from the Releases page
  2. Double-click the downloaded .pkg file
  3. Follow the installation wizard

Or via command line:

# Download the installer (replace VERSION with the actual version)
curl -LO https://github.com/containers/ramalama/releases/download/vVERSION/RamaLama-VERSION-macOS-Installer.pkg

# Verify the SHA256 checksum (optional but recommended)
curl -LO https://github.com/containers/ramalama/releases/download/vVERSION/RamaLama-VERSION-macOS-Installer.pkg.sha256
shasum -a 256 -c RamaLama-VERSION-macOS-Installer.pkg.sha256

# Install
sudo installer -pkg RamaLama-VERSION-macOS-Installer.pkg -target /

What Gets Installed

The installer places files in:

  • /usr/local/bin/ramalama - Main executable
  • /usr/local/share/man/ - Man pages
  • /usr/local/share/bash-completion/ - Bash completions
  • /usr/local/share/fish/ - Fish completions
  • /usr/local/share/zsh/ - Zsh completions
  • /Applications/ramalama.app - App bundle containing configuration files, resources, Python dependencies, etc.

Verify Installation

# Check version
ramalama --version

# Get help
ramalama --help

Method 2: Python Package (pip)

If you prefer to use Python package management:

# Install Python 3.10 or later (if not already installed)
brew install python@3.11

# Install ramalama
pip3 install ramalama

# Or install from source
git clone https://github.com/containers/ramalama.git
cd ramalama
pip3 install .

Method 3: Build from Source

For developers or if you want the latest code:

# Clone the repository
git clone https://github.com/containers/ramalama.git
cd ramalama

# Install build dependencies
pip3 install build

# Build and install
make install

Prerequisites

Before using RamaLama, you'll need a container engine:

Option A: Podman (Recommended)

brew install podman

# Initialize Podman machine with libkrun for GPU access
podman machine init --provider libkrun
podman machine start

For more details, see ramalama-macos(7).

Option B: Docker

brew install docker

Building the Installer Package (For Maintainers)

If you want to build the installer package yourself:

# Install PyInstaller
pip3 install pyinstaller

# Build the package
./scripts/build_macos_pkg.sh

# The built package will be in:
# build/macos-pkg/RamaLama-VERSION-macOS-Installer.pkg

Uninstallation

To remove RamaLama:

# Remove the executable
sudo rm /usr/local/bin/ramalama

# Remove the app bundle
sudo rm -rf /Applications/ramalama.app

# Remove configuration and data files (optional)
rm -rf ~/.local/share/ramalama
rm -rf ~/.config/ramalama

# Remove man pages (optional)
sudo rm /usr/local/share/man/man1/ramalama*.1
sudo rm /usr/local/share/man/man5/ramalama*.5
sudo rm /usr/local/share/man/man7/ramalama*.7

# Remove shell completions (optional)
sudo rm /usr/local/share/bash-completion/completions/ramalama
sudo rm /usr/local/share/fish/vendor_completions.d/ramalama.fish
sudo rm /usr/local/share/zsh/site-functions/_ramalama

Troubleshooting

"ramalama: command not found"

Make sure /usr/local/bin is in your PATH:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

"Cannot verify developer" warning

macOS may show a security warning for unsigned packages. NOTE: We're working on getting keys to sign it.

To bypass:

  1. Right-click the .pkg file
  2. Select "Open"
  3. Click "Open" in the dialog

Podman machine issues

If Podman isn't working:

# Reset Podman machine
podman machine stop
podman machine rm
podman machine init --provider libkrun
podman machine start

Getting Started

Once installed, try these commands:

# Check version
ramalama --version

# Pull a model
ramalama pull tinyllama

# Run a chatbot
ramalama run tinyllama

# Get help
ramalama --help

Additional Resources

System Requirements

  • macOS 10.15 (Catalina) or later
  • Intel or Apple Silicon (M1/M2/M3) processor
  • 4GB RAM minimum (8GB+ recommended for running models)
  • 10GB free disk space
  • Podman or Docker
View Git Blame Copy Permalink