Installation Guide

Install Cassandra on macOS

Easy installation with Homebrew or manual setup - perfect for development!

Home › Installation › Install on macOS

🍎 macOS: Great for Development!

✅ Why macOS is Good for Cassandra

  • ✅ Unix-based: Same command-line tools as Linux
  • ✅ Homebrew: Super easy installation (1 command!)
  • ✅ Better than Windows: Native Unix environment
  • ✅ Developer friendly: Excellent for learning and building apps
  • ✅ Works on M1/M2/M3: Apple Silicon support

⚠️ Still: Not for Production

While better than Windows, macOS is still NOT recommended for production:

  • ⚠️ Performance: 10-20% slower than Linux
  • ⚠️ macOS servers rare: Most production runs Linux
  • ⚠️ License costs: macOS Server discontinued

💡 Best Use Cases

  • ✅ Learning Cassandra: Perfect for tutorials
  • ✅ Local development: Building macOS/iOS apps
  • ✅ Testing queries: CQL practice
  • ✅ Prototyping: Quick proof-of-concepts
  • 🐳 For production testing: Use Docker or Linux VM

🚀 Let's install Cassandra on your Mac!

🎯 Choose Your Installation Method

Two options: Easy Homebrew or Manual installation.

🍺

Homebrew Method

Recommended for most users!

  • ✅ Super easy: 3 commands!
  • ✅ Auto-updates: brew upgrade
  • ✅ Dependencies handled: Java installed automatically
  • ✅ Service management: Start/stop easily
  • ✅ Clean uninstall: brew uninstall

→ Jump to Homebrew installation

📦

Manual Installation

For advanced users

  • ⚙️ More control: Choose versions
  • ⚙️ Multiple versions: Run different Cassandra versions
  • ⚙️ Custom configs: Full control
  • ❌ More work: Manual updates
  • ❌ Manual cleanup: No package manager

→ Jump to Manual installation

Not Sure Which to Choose?

Choose Homebrew if:

  • You're new to Cassandra
  • You want the easiest installation
  • You already use Homebrew for other tools

Choose Manual if:

  • You need a specific Cassandra version
  • You want to run multiple versions
  • You prefer full control over installation

🍺 Method 1: Homebrew Installation (Recommended)

The easiest way to install Cassandra on macOS!

1

Install Homebrew (if not installed)

First, check if you have Homebrew:

# Check if Homebrew is installed brew --version

If not installed, install Homebrew:

# Install Homebrew (paste this in Terminal) /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Follow the on-screen instructions # Add Homebrew to PATH (M1/M2/M3 Macs) echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile eval "$(/opt/homebrew/bin/brew shellenv)"
2

Install Java (OpenJDK 11)

Cassandra needs Java. Install via Homebrew:

# Install OpenJDK 11 brew install openjdk@11 # Link Java (so system can find it) sudo ln -sfn /opt/homebrew/opt/openjdk@11/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-11.jdk # Verify Java installation java -version # Expected output: # openjdk version "11.0.x"
3

Install Cassandra with Homebrew

Now install Cassandra (this installs everything automatically!):

# Install Cassandra brew install cassandra # This will: # - Download Cassandra # - Install all dependencies # - Set up configuration files # - Create data directories

Wait for installation to complete (2-3 minutes).

4

Start Cassandra Service

Start Cassandra as a background service:

# Start Cassandra (runs in background) brew services start cassandra # Check if it's running brew services list # Expected output: # cassandra started ~/Library/LaunchAgents/homebrew.mxcl.cassandra.plist

First startup takes 30-60 seconds! Be patient.

5

Verify Installation

Test that Cassandra is working:

# Check node status nodetool status # Expected output: # UN 127.0.0.1 69.91 KiB 16 100.0% ... # UN = Up and Normal (success!) # Connect to CQL shell cqlsh # Expected output: # Connected to Test Cluster at 127.0.0.1:9042 # cqlsh> # Test a query SELECT release_version FROM system.local; # Exit cqlsh exit

Homebrew Installation Complete! 🎉

Useful Homebrew commands:

  • brew services start cassandra - Start Cassandra
  • brew services stop cassandra - Stop Cassandra
  • brew services restart cassandra - Restart Cassandra
  • brew upgrade cassandra - Update to latest version
  • brew uninstall cassandra - Remove Cassandra

Configuration file location:
/opt/homebrew/etc/cassandra/cassandra.yaml

Data directory:
/opt/homebrew/var/lib/cassandra

Logs:
/opt/homebrew/var/log/cassandra

M1/M2/M3 Mac Users (Apple Silicon)

If you have an Apple Silicon Mac, paths might be different:

  • Homebrew location: /opt/homebrew/ (not /usr/local/)
  • Java location: /opt/homebrew/opt/openjdk@11/
  • Everything else works the same!

📦 Method 2: Manual Installation

For users who want more control over the installation.

1

Install Java Manually

Download and install OpenJDK 11:

# Option 1: Use Homebrew (easiest) brew install openjdk@11 # Option 2: Download from Adoptium # Visit: https://adoptium.net/temurin/releases/?os=mac # Download the .pkg file for macOS # Double-click to install # Verify Java java -version
2

Download Cassandra

# Create directory for Cassandra sudo mkdir -p /usr/local/cassandra cd /usr/local/cassandra # Download Cassandra (replace X with actual version) curl -O https://dlcdn.apache.org/cassandra/4.1.4/apache-cassandra-4.1.4-bin.tar.gz # Extract tar -xzf apache-cassandra-4.1.4-bin.tar.gz # Create symlink for easier access sudo ln -s apache-cassandra-4.1.4 cassandra # Verify extraction ls -la cassandra/
3

Set Environment Variables

Add Cassandra to your PATH. Edit ~/.zshrc (or ~/.bash_profile):

# Open config file in nano editor nano ~/.zshrc # Add these lines at the end: export CASSANDRA_HOME="/usr/local/cassandra/cassandra" export PATH="$CASSANDRA_HOME/bin:$PATH" # Save: Ctrl+O, Enter, Ctrl+X # Apply changes source ~/.zshrc # Verify echo $CASSANDRA_HOME
4

Create Data Directories

# Create directories for Cassandra data sudo mkdir -p /var/lib/cassandra/data sudo mkdir -p /var/lib/cassandra/commitlog sudo mkdir -p /var/lib/cassandra/saved_caches sudo mkdir -p /var/lib/cassandra/hints sudo mkdir -p /var/log/cassandra # Set permissions (replace 'username' with your Mac username) sudo chown -R $(whoami) /var/lib/cassandra sudo chown -R $(whoami) /var/log/cassandra
5

Configure cassandra.yaml

Edit the configuration file:

# Open cassandra.yaml nano $CASSANDRA_HOME/conf/cassandra.yaml # Verify these settings (should be default): data_file_directories: - /var/lib/cassandra/data commitlog_directory: /var/lib/cassandra/commitlog saved_caches_directory: /var/lib/cassandra/saved_caches hints_directory: /var/lib/cassandra/hints # Save and exit: Ctrl+O, Enter, Ctrl+X
6

Start Cassandra

# Start Cassandra in foreground (logs to terminal) cassandra -f # OR start in background cassandra # Wait 30-60 seconds for startup # Check if running nodetool status

⚙️ Configuration Tips

Optional: Optimize Cassandra for your Mac.

Adjust JVM Heap Size

For Macs with 8GB+ RAM, you can increase heap size:

# Homebrew installation: nano /opt/homebrew/etc/cassandra/jvm-server.options # Manual installation: nano $CASSANDRA_HOME/conf/jvm-server.options # Or for Java 11: nano $CASSANDRA_HOME/conf/jvm11-server.options # Modify heap settings: # For 8GB RAM Mac: -Xms2G -Xmx2G # For 16GB RAM Mac: -Xms4G -Xmx4G

macOS Resource Limits

macOS has strict resource limits. If you encounter errors, increase them:

# Check current limits ulimit -a # Increase file descriptor limit (temporary) ulimit -n 10240 # Make permanent: Add to ~/.zshrc echo 'ulimit -n 10240' >> ~/.zshrc

✅ Verify Installation

Test that everything works correctly!

1

Check Cassandra Status

# Check node status nodetool status # Expected output: Datacenter: datacenter1 ======================= Status=Up/Down |/ State=Normal/Leaving/Joining/Moving -- Address Load Tokens Owns Host ID Rack UN 127.0.0.1 69.91 KiB 16 100.0% 8d5ed3f4-7764-4dbd-bad8-43fddce94b7c rack1 # UN = Up and Normal ✅
2

Connect with cqlsh

# Start CQL shell cqlsh # Expected output: Connected to Test Cluster at 127.0.0.1:9042 [cqlsh 6.1.0 | Cassandra 4.1.4 | CQL spec 3.4.6 | Native protocol v5] Use HELP for help. cqlsh>
3

Run Test Queries

-- Check Cassandra version SELECT release_version FROM system.local; -- Create test keyspace CREATE KEYSPACE test_ks WITH REPLICATION = { 'class': 'SimpleStrategy', 'replication_factor': 1 }; -- Use keyspace USE test_ks; -- Create table CREATE TABLE users ( id UUID PRIMARY KEY, name TEXT, email TEXT ); -- Insert data INSERT INTO users (id, name, email) VALUES (uuid(), 'Alice', 'alice@example.com'); INSERT INTO users (id, name, email) VALUES (uuid(), 'Bob', 'bob@example.com'); -- Query data SELECT * FROM users; -- Exit EXIT;

Installation Successful! 🎉

You now have Cassandra running on macOS!

  • ✅ Cassandra server running
  • ✅ cqlsh working
  • ✅ Can create keyspaces and tables
  • ✅ Ready to build applications!

🔧 Common Issues & Solutions

Fix common macOS installation problems!

❌ "command not found: cqlsh"

Problem: PATH not set correctly

Solution:

# Homebrew: Check if service is running brew services list # Manual: Check if PATH is set echo $CASSANDRA_HOME # If empty, add to ~/.zshrc: export PATH="/usr/local/cassandra/cassandra/bin:$PATH" source ~/.zshrc

❌ "Cannot allocate memory" or OutOfMemory errors

Problem: JVM heap too large for your Mac

Solution:

# Reduce heap size in jvm-server.options # For 8GB Mac: -Xms1G -Xmx1G # Restart Cassandra brew services restart cassandra

❌ "Address already in use (port 9042 or 7000)"

Problem: Another Cassandra instance running

Solution:

# Find process using port lsof -i :9042 # Kill the process (replace PID) kill -9 PID # Or stop via Homebrew brew services stop cassandra brew services start cassandra

❌ Cassandra starts but crashes immediately

Possible causes:

  • Wrong Java version: Must be Java 11 or 17
  • Corrupt data: Delete data directory
  • Permission issues: Check directory ownership

Check logs:

# Homebrew logs tail -f /opt/homebrew/var/log/cassandra/system.log # Manual installation logs tail -f /var/log/cassandra/system.log

❌ "Too many open files" error

Problem: macOS file descriptor limit

Solution:

# Increase limit temporarily ulimit -n 10240 # Make permanent: add to ~/.zshrc echo 'ulimit -n 10240' >> ~/.zshrc source ~/.zshrc # Restart Cassandra brew services restart cassandra

❌ Python/cqlsh issues on M1/M2/M3 Macs

Problem: Python compatibility with Apple Silicon

Solution:

# Install Python 3 via Homebrew brew install python@3 # Install cassandra-driver pip3 install cassandra-driver # Use python3 explicitly python3 $CASSANDRA_HOME/bin/cqlsh.py

Still Having Problems?

Reset and start fresh:

# Homebrew: Complete uninstall brew services stop cassandra brew uninstall cassandra rm -rf /opt/homebrew/var/lib/cassandra rm -rf /opt/homebrew/var/log/cassandra # Reinstall brew install cassandra brew services start cassandra # Or try Docker instead! # Much easier: docker run -p 9042:9042 cassandra:4.1

🎉 What's Next?

Congratulations! You've successfully installed Cassandra on macOS!

🚀 Continue Your Learning:

💡 Useful Commands:

# Start Cassandra brew services start cassandra # Stop Cassandra brew services stop cassandra # Restart Cassandra brew services restart cassandra # Check status nodetool status # Connect to CQL cqlsh # View logs tail -f /opt/homebrew/var/log/cassandra/system.log

🍎 macOS Tips:

  • 🔋 Battery life: Stop Cassandra when not using (brew services stop cassandra)
  • 💾 Backups: Data in /opt/homebrew/var/lib/cassandra
  • 🐳 For production testing: Use Docker or Linux VM
  • ⚡ Performance: macOS 10-20% slower than Linux

🎓 Ready to build amazing applications with Cassandra!

Previous
Install on Windows
Advertisement

Responsive Ad