Skip to main content

Installation Guide - macOS

This guide will walk you through setting up MLVisual on macOS step by step.

📋 Prerequisites​

  • macOS 10.15 (Catalina) or higher
  • 8GB RAM minimum (16GB recommended)
  • 10GB free disk space
  • Internet connection
  • Terminal (native macOS application)

🚀 Step-by-Step Installation​

1. Install Homebrew (Package Manager)​

Install Homebrew​

Open Terminal and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Verify Installation​

brew --version

2. Install Unity 2022.3 LTS​

Download Unity Hub​

  1. Go to unity.com/download
  2. Download Unity Hub for macOS
  3. Drag Unity Hub to the Applications folder
  4. Open Unity Hub from Applications

Install Unity Editor​

  1. Open Unity Hub
  2. Go to the "Installs" tab
  3. Click "Install Editor"
  4. Select Unity 2022.3.XX LTS (the latest version)
  5. In "Add Modules", select:
    • ✅ Xcode (for iOS development)
    • ✅ WebGL Build Support (for web demos)
    • ✅ Android Build Support (optional)
  6. Click "Install" and wait for it to finish

3. Install Python 3.8+​

Install Python using Homebrew​

# Install Python
brew install python@3.9

# Verify installation
python3 --version
pip3 --version

Configure Alias (Optional)​

To use python instead of python3:

# Add to your shell profile
echo 'alias python=python3' >> ~/.zshrc
echo 'alias pip=pip3' >> ~/.zshrc

# Reload configuration
source ~/.zshrc

4. Set Up Virtual Environment​

Create the Environment​

# Navigate to your projects directory
cd ~/Documents

# Create directory if it doesn't exist
mkdir -p mlvisual-projects
cd mlvisual-projects

# Create virtual environment
python3 -m venv mlvisual-env

# Activate the environment
source mlvisual-env/bin/activate

Verify it Works​

# You should see (mlvisual-env) at the beginning of your prompt
which python
# Should point to your virtual environment

5. Install mlvlab​

# Make sure your virtual environment is active
# You should see (mlvisual-env) in your prompt

# Update pip
python -m pip install --upgrade pip

# Install mlvlab
pip install mlvlab

# Verify installation
python -c "import mlvlab; print('mlvlab installed correctly')"

6. Install Additional Dependencies​

# Essential libraries for RL
pip install numpy pandas matplotlib seaborn
pip install gymnasium stable-baselines3
pip install jupyter notebook

# For visualization and debugging
pip install tensorboard wandb

# For development
pip install black flake8 pytest

# System dependencies for matplotlib
brew install freetype

7. Configure Unity for mlvlab​

Install the mlvlab Package​

  1. Open Unity Hub
  2. Create a new 3D project
  3. Go to Window > Package Manager
  4. Click the "+" in the top left corner
  5. Select "Add package from git URL"
  6. Enter: https://github.com/mlvisual/mlvlab-unity.git
  7. Click "Add"

Verify Installation​

  1. In Unity, go to Assets > Create > mlvlab
  2. You should see options like "Test Environment"
  3. If there are no errors, everything is working!

✅ Complete Verification​

Python Test​

Create a file test_installation.py:

import mlvlab
import numpy as np
import matplotlib.pyplot as plt
import gymnasium as gym

print("✅ mlvlab imported correctly")
print("✅ numpy working")
print("✅ matplotlib working")
print("✅ gymnasium working")
print("✅ Installation complete!")

Unity Test​

  1. Open Unity Hub
  2. Create a new 3D project
  3. Go to Assets > Create > mlvlab > Test Environment
  4. If there are no errors, everything is working!

🔧 macOS-Specific Troubleshooting​

Error: "command not found: python"​

Cause: Python not in PATH Solution:

# Verify Python is installed
which python3

# If not, install it
brew install python@3.9

# Verify version
python3 --version

Error: "command not found: pip"​

Solution:

# Install pip if not present
brew install python@3.9

# Or use python3 -m pip
python3 -m pip install --upgrade pip

Error: "mlvlab not found"​

Cause: Virtual environment not activated Solution:

# Navigate to your project directory
cd ~/Documents/mlvisual-projects

# Activate the environment
source mlvisual-env/bin/activate

# Verify it's active (you should see (mlvisual-env))
pip list

Unity can't find mlvlab​

Solution:

  1. Verify the package is installed in Package Manager
  2. Restart Unity
  3. Verify you're using Unity 2022.3 LTS

Permission errors on macOS​

Solution:

# Change directory permissions
sudo chown -R $USER:staff ~/mlvisual-projects

# Or use sudo if necessary
sudo pip install mlvlab

matplotlib issues on macOS​

Solution:

# Install system dependencies
brew install freetype libpng

# Reinstall matplotlib
pip uninstall matplotlib
pip install matplotlib

Homebrew installation issues​

Solution:

# Update Homebrew
brew update

# Fix permissions
sudo chown -R $(whoami) /usr/local/share/zsh /usr/local/share/zsh/site-functions

# Reinstall Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Xcode command line tools missing​

Solution:

# Install Xcode command line tools
xcode-select --install

# Verify installation
xcode-select -p

🎉 Ready to Get Started!​

Now you have everything set up on macOS. You can:

  1. Explore the Glossary to understand the terms
  2. Read the Theoretical Articles to dive deeper into theory
  3. Start with the Laboratories to practice

📞 Need Help?​

If you encounter any macOS-specific issues:

  1. Check the Troubleshooting section above
  2. Search our Glossary to understand terms
  3. Consult the Articles for theoretical concepts
  4. Join our community for support

Congratulations! You've set up MLVisual on macOS correctly.