diff --git a/README.md b/README.md
index c1f46f5..cbd06f9 100644
--- a/README.md
+++ b/README.md
@@ -48,10 +48,25 @@ Instead of running one test case, Flakestorm takes a single "Golden Prompt", gen
 
 ### Installation
 
+**Using a virtual environment (recommended):**
+
 ```bash
+# Create and activate virtual environment
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install flakestorm
 pip install flakestorm
 ```
 
+**Or using pipx (for CLI use only):**
+
+```bash
+pipx install flakestorm
+```
+
+**Note:** Requires Python 3.10 or higher. On macOS, Python environments are externally managed, so using a virtual environment is required.
+
 ### Prerequisites
 
 Flakestorm uses [Ollama](https://ollama.ai) for local model inference:
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index cd9cfbf..557e9d6 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -20,6 +20,11 @@ Please be respectful and constructive in all interactions. We welcome contributo
    ```bash
    python -m venv .venv
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   # Create virtual environment first
+   python3 -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+   # Then install in editable mode
    pip install -e ".[dev]"
    ```
 
diff --git a/docs/TESTING_GUIDE.md b/docs/TESTING_GUIDE.md
index c6d633b..d413d3f 100644
--- a/docs/TESTING_GUIDE.md
+++ b/docs/TESTING_GUIDE.md
@@ -23,6 +23,11 @@ This guide explains how to run, write, and expand tests for flakestorm. It cover
 
 ```bash
 # Install dev dependencies
+# Create virtual environment first
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Then install
 pip install -e ".[dev]"
 
 # Or manually
diff --git a/docs/TEST_SCENARIOS.md b/docs/TEST_SCENARIOS.md
index 544d1dd..545ddc7 100644
--- a/docs/TEST_SCENARIOS.md
+++ b/docs/TEST_SCENARIOS.md
@@ -605,6 +605,11 @@ The mutation engine will generate attacks like:
 
 ```bash
 # In your agent project directory
+# Create virtual environment first
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Then install
 pip install flakestorm
 
 # Initialize configuration
diff --git a/docs/USAGE_GUIDE.md b/docs/USAGE_GUIDE.md
index d4e28e4..a1ce900 100644
--- a/docs/USAGE_GUIDE.md
+++ b/docs/USAGE_GUIDE.md
@@ -115,7 +115,19 @@ ollama run qwen2.5-coder:7b "Hello, world!"
 
 ### Step 3: Install flakestorm
 
+**Important:** On macOS (and some Linux distributions), Python environments are externally managed. You should use a virtual environment:
+
 ```bash
+# Create a virtual environment
+python3 -m venv venv
+
+# Activate it (macOS/Linux)
+source venv/bin/activate
+
+# Activate it (Windows)
+# venv\Scripts\activate
+
+# Now install flakestorm
 # From PyPI (when published)
 pip install flakestorm
 
@@ -125,12 +137,31 @@ cd flakestorm
 pip install -e ".[dev]"
 ```
 
+**Alternative: Using pipx (for CLI applications)**
+
+If you only want to use flakestorm as a CLI tool (not develop it), you can use `pipx`:
+
+```bash
+# Install pipx (if not already installed)
+brew install pipx  # macOS
+# Or: python3 -m pip install --user pipx
+
+# Install flakestorm
+pipx install flakestorm
+```
+
+**Note:** Make sure you're using Python 3.10+. You can verify with:
+```bash
+python3 --version  # Should be 3.10 or higher
+```
+
 ### Step 4: (Optional) Install Rust Extension
 
 For 80x+ performance improvement on scoring:
 
 ```bash
 cd rust
+# Make sure virtual environment is activated
 pip install maturin
 maturin build --release
 pip install ../target/wheels/*.whl