Troubleshooting Guide¶

Common issues and solutions for Zero to AI learning path.

� Quick Fixes (Most Common Issues)¶

Having trouble? Try these first:

Environment not activating?

source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

Import errors?
```
pip install -r requirements.txt
```

Jupyter won’t start?

pip install jupyter notebook
jupyter notebook --no-browser

CUDA not working?

# Check PyTorch CUDA availability
import torch
print(torch.cuda.is_available())

Wrong Python version?
```
python --version  # Should be 3.9+
```

Still stuck? See detailed solutions below or run the diagnostic script.

🔍 Error Message Quick Reference¶

Jump directly to solutions for common error messages:

Error Message	Category	Quick Fix	Details
`ModuleNotFoundError: No module named 'X'`	Import	`pip install package-name`	Package Import Errors
`CUDA error: out of memory`	GPU	Reduce batch size	GPU/CUDA Issues
`pip install fails with permission errors`	Installation	Use virtual environment	Installation Issues
`ImportError: DLL load failed`	Windows	Reinstall Visual C++	Platform-Specific Issues
`conda command not found`	Environment	Install Miniconda	Installation Issues
`Jupyter kernel keeps dying`	Jupyter	Reduce memory usage	Jupyter Notebook Issues
`RuntimeError: CUDA not available`	GPU	Install PyTorch with CUDA	GPU/CUDA Issues
`SyntaxError: invalid syntax`	Python	Check Python version (3.9+)	Environment Problems
`Virtual environment not activating`	Environment	Check activation command	Environment Problems
`SSL certificate errors`	macOS	Install certificates	Platform-Specific Issues

📊 Compatibility Matrix¶

Recommended versions and compatibility information:

Core Dependencies¶

Component	Minimum	Recommended	Tested Versions	Notes
Python	3.9	3.11	3.9, 3.10, 3.11, 3.12	3.12 may have package compatibility issues
pip	21.0	Latest	23.0+	Use `pip install --upgrade pip`
Jupyter	1.0	Latest	1.0+	Includes notebook and lab
NumPy	1.21	1.26+	1.21-1.26	Core numerical computing
Pandas	1.3	2.0+	1.3-2.1	Data manipulation
Scikit-learn	1.0	1.4+	1.0-1.4	Traditional ML

Deep Learning Frameworks¶

Framework	Minimum	Recommended	CUDA Support	Notes
PyTorch	2.0	2.2+	CUDA 11.8, 12.1	Main framework
TensorFlow	2.10	2.15+	CUDA 11.8	Optional
Transformers	4.30	4.37+	-	HuggingFace library

GPU/CUDA Compatibility¶

GPU Series	CUDA Version	PyTorch Command
RTX 40XX	12.1	`pip install torch --index-url https://download.pytorch.org/whl/cu121`
RTX 30XX	11.8 or 12.1	`pip install torch --index-url https://download.pytorch.org/whl/cu118`
RTX 20XX / GTX 16XX	11.8	`pip install torch --index-url https://download.pytorch.org/whl/cu118`
GTX 10XX	11.8	`pip install torch --index-url https://download.pytorch.org/whl/cu118`
CPU Only	N/A	`pip install torch`

Platform-Specific¶

Platform	Python Install	Package Manager	GPU Support
macOS (Intel)	python.org or Homebrew	pip or conda	No CUDA (MPS for M1/M2)
macOS (M1/M2/M3)	python.org or conda	conda preferred	Metal Performance Shaders
Windows	python.org	pip or conda	CUDA supported
Linux	System package manager	pip or conda	CUDA supported

Last Updated: March 2026

Installation Issues¶

Problem: `pip install` fails with permission errors¶

Solution:

# Use --user flag
pip install --user -r requirements.txt

# Or use virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

Problem: `conda` command not found¶

Solution:

# Install Miniconda
# macOS/Linux:
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

# Or download from https://docs.conda.io/en/latest/miniconda.html
# Then restart your terminal

Problem: UV installation fails¶

Solution:

# Alternative installation methods
# Using pip:
pip install uv

# Using Homebrew (macOS):
brew install uv

# Manual download from:
# https://github.com/astral-sh/uv/releases

Environment Problems¶

Problem: Wrong Python version¶

Solution:

# Check Python version
python --version

# Should be Python 3.9 or higher
# If not, install correct version:

# Using conda:
conda create -n aiml-learning python=3.11
conda activate aiml-learning

# Using pyenv:
pyenv install 3.11.0
pyenv local 3.11.0

Problem: Virtual environment not activating¶

Solution:

# macOS/Linux:
source .venv/bin/activate

# Windows (Command Prompt):
.venv\Scripts\activate.bat

# Windows (PowerShell):
.venv\Scripts\Activate.ps1

# If PowerShell gives execution policy error:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problem: Environment packages not found after activation¶

Solution:

# Verify environment is active
which python  # macOS/Linux
where python  # Windows

# Should point to .venv/bin/python or similar
# If not, deactivate and reactivate:
deactivate
source .venv/bin/activate

# Reinstall packages:
pip install -r requirements.txt

Jupyter Notebook Issues¶

Problem: Jupyter not found¶

Solution:

# Install Jupyter
pip install jupyter notebook

# Verify installation
jupyter --version

# Launch Jupyter
jupyter notebook

Problem: Kernel not found or wrong kernel¶

Solution:

# Install ipykernel
pip install ipykernel

# Add current environment to Jupyter
python -m ipykernel install --user --name=aiml-learning --display-name "Python (AI/ML)"

# In Jupyter, select: Kernel > Change Kernel > Python (AI/ML)

Problem: Jupyter kernel keeps dying¶

Solutions:

Reduce memory usage:

# In your notebook, clear variables
%reset -f

# Import garbage collector
import gc
gc.collect()

Increase memory limits:

# Start Jupyter with more memory
jupyter notebook --NotebookApp.max_buffer_size=1000000000

Check logs:

# View Jupyter logs
jupyter notebook --debug

Problem: Cannot open notebooks¶

Solution:

# Try opening specific notebook
jupyter notebook path/to/notebook.ipynb

# If file association broken, reinstall:
pip uninstall jupyter notebook
pip install jupyter notebook

Package Import Errors¶

Problem: `ModuleNotFoundError: No module named 'X'`¶

Solution:

# Install missing package
pip install package-name

# For common packages:
pip install numpy pandas matplotlib scikit-learn

# For deep learning:
pip install torch torchvision
pip install tensorflow

# For NLP:
pip install transformers tokenizers

# Install everything:
pip install -r requirements.txt

Problem: Import works in terminal but not in Jupyter¶

Solution:

# Verify Jupyter is using correct Python
# In Jupyter notebook:
import sys
print(sys.executable)

# Should match your virtual environment
# If not, reinstall kernel:
python -m ipykernel install --user --name=aiml-learning --display-name "Python (AI/ML)"

Problem: Package version conflicts¶

Solution:

# Create fresh environment
conda create -n aiml-fresh python=3.11
conda activate aiml-fresh

# Install packages one group at a time:
pip install numpy pandas matplotlib scikit-learn
pip install torch torchvision
pip install transformers

# Check for conflicts:
pip check

GPU/CUDA Issues¶

Problem: PyTorch not using GPU¶

Solution:

import torch

# Check CUDA availability
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")
print(f"GPU device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'None'}")

# If False, reinstall PyTorch with CUDA:
# Visit: https://pytorch.org/get-started/locally/
# Select your OS, Package, and CUDA version

Example installation commands:

# For CUDA 11.8:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# For CUDA 12.1:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# For CPU only:
pip install torch torchvision torchaudio

Problem: CUDA out of memory¶

Solutions:

# 1. Reduce batch size
batch_size = 8  # Instead of 32

# 2. Use gradient accumulation
# Simulate larger batch size
accumulation_steps = 4

# 3. Clear CUDA cache
import torch
torch.cuda.empty_cache()

# 4. Use mixed precision training
from torch.cuda.amp import autocast, GradScaler

# 5. Use gradient checkpointing
model.gradient_checkpointing_enable()

Problem: Multiple CUDA versions¶

Solution:

# Check installed CUDA version
nvcc --version

# Check PyTorch CUDA version
python -c "import torch; print(torch.version.cuda)"

# Ensure they match
# Reinstall PyTorch if needed (see above)

Memory Issues¶

Problem: Jupyter notebook crashes with large datasets¶

Solutions:

# 1. Use chunking for large files
import pandas as pd

# Instead of:
# df = pd.read_csv('large_file.csv')

# Use:
chunks = pd.read_csv('large_file.csv', chunksize=10000)
for chunk in chunks:
    process(chunk)

# 2. Use efficient dtypes
df = pd.read_csv('file.csv', dtype={'column': 'int32'})

# 3. Free memory
del large_object
import gc
gc.collect()

Problem: RAM usage grows over time¶

Solution:

# Monitor memory usage
import psutil
import os

def get_memory_usage():
    process = psutil.Process(os.getpid())
    return process.memory_info().rss / 1024 / 1024  # MB

print(f"Memory usage: {get_memory_usage():.2f} MB")

# Clear variables regularly
%reset -f  # In Jupyter

# Use context managers
with open('file.txt') as f:
    data = f.read()
    # process data
# file automatically closed

Platform-Specific Issues¶

macOS¶

Problem: SSL certificate errors¶

Solution:

# Install certificates
/Applications/Python\ 3.x/Install\ Certificates.command

# Or manually:
pip install --upgrade certifi

Problem: M1/M2 compatibility issues¶

Solution:

# Use Conda for better M1/M2 support
conda create -n aiml-learning python=3.11
conda activate aiml-learning

# Install packages via conda when possible
conda install numpy pandas scikit-learn
conda install pytorch torchvision -c pytorch

Windows¶

Problem: Long path names¶

Solution:

# Enable long path support (Windows 10+)
# Run as Administrator in PowerShell:
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

# Or clone to shorter path:
git clone https://github.com/PavanMudigonda/zero-to-ai.git C:\ai

Problem: Visual C++ redistributable missing¶

Solution:

Download from: https://aka.ms/vs/17/release/vc_redist.x64.exe
Install and restart computer

Linux¶

Problem: `python3-dev` missing¶

Solution:

# Ubuntu/Debian:
sudo apt-get update
sudo apt-get install python3-dev python3-pip

# Fedora/RHEL:
sudo dnf install python3-devel

# Arch:
sudo pacman -S python python-pip

Common Error Messages¶

`ImportError: DLL load failed`¶

Windows Solution:

# Install/reinstall Visual C++ Redistributable
# Download from Microsoft
# Reinstall numpy
pip uninstall numpy
pip install numpy

`RuntimeError: CUDA error: out of memory`¶

Solution:

# Reduce batch size
batch_size = batch_size // 2

# Clear CUDA cache
torch.cuda.empty_cache()

# Or use CPU
device = 'cpu'

`SyntaxError: invalid syntax`¶

Solution:

# Check Python version
python --version

# Ensure using Python 3.9+
# Check for Python 2 vs 3 issues
which python
which python3

Getting More Help¶

If your issue isn’t listed here:

Search existing issues: GitHub Issues
Check discussions: GitHub Discussions
Create new issue: New Issue
Run diagnostics: Use the Quick Diagnosis Script above

When Asking for Help¶

Include:

Operating system and version
Python version (python --version)
Error message (full traceback)
Steps to reproduce
What you’ve already tried

Quick Diagnosis Script¶

🔧 One-Command Diagnostics¶

Quick environment checks (copy and paste):

# Check Python version and location
python --version && which python

# Verify key packages in one line
python -c "import sys; import numpy as np; import pandas as pd; import sklearn; import torch; print(f'✅ Python {sys.version_info.major}.{sys.version_info.minor} | NumPy {np.__version__} | Pandas {pd.__version__} | PyTorch {torch.__version__} | CUDA: {torch.cuda.is_available()}')"

# Check CUDA setup
python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}'); print(f'CUDA Version: {torch.version.cuda}' if torch.cuda.is_available() else 'CPU Only'); print(f'GPU: {torch.cuda.get_device_name(0)}' if torch.cuda.is_available() else 'No GPU')"

# List installed packages
pip list | grep -E 'numpy|pandas|torch|transformers|jupyter'

📝 Comprehensive Diagnostic Script¶

Run this complete diagnostic to check your environment:

#!/usr/bin/env python3
"""Comprehensive environment diagnostic script for Zero to AI"""

import sys
import platform
import subprocess

print("=" * 60)
print("ZERO TO AI - ENVIRONMENT DIAGNOSTICS")
print("=" * 60)

# System Information
print("\n📋 SYSTEM INFORMATION")
print("-" * 60)
print(f"Platform: {platform.platform()}")
print(f"Python Version: {sys.version}")
print(f"Python Executable: {sys.executable}")
print(f"Architecture: {platform.machine()}")

# Check Python version compatibility
python_version = sys.version_info
if python_version >= (3, 9):
    print(f"✅ Python version {python_version.major}.{python_version.minor} is compatible")
else:
    print(f"❌ Python {python_version.major}.{python_version.minor} detected. Please upgrade to 3.9+")

# Package Checks
print("\n📦 CHECKING PACKAGES")
print("-" * 60)

packages = [
    'numpy', 'pandas', 'matplotlib', 'scikit-learn',
    'torch', 'torchvision', 'transformers', 'tokenizers',
    'jupyter', 'notebook', 'ipykernel'
]

missing_packages = []

for package in packages:
    try:
        mod = __import__(package.replace('-', '_'))
        version = getattr(mod, '__version__', 'Unknown')
        print(f"✅ {package:20s} {version}")
    except ImportError:
        print(f"❌ {package:20s} NOT INSTALLED")
        missing_packages.append(package)

# GPU/CUDA Check
print("\n🎮 GPU/CUDA STATUS")
print("-" * 60)
try:
    import torch
    cuda_available = torch.cuda.is_available()
    print(f"CUDA Available: {'✅ YES' if cuda_available else '❌ NO'}")
    
    if cuda_available:
        print(f"CUDA Version: {torch.version.cuda}")
        print(f"GPU Device: {torch.cuda.get_device_name(0)}")
        print(f"GPU Memory: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.2f} GB")
    else:
        print("Running in CPU-only mode")
        print("For GPU support, install PyTorch with CUDA:")
        print("  pip install torch --index-url https://download.pytorch.org/whl/cu118")
    
    # Check MPS (Apple Silicon)
    if hasattr(torch.backends, 'mps') and torch.backends.mps.is_available():
        print("✅ Apple Metal Performance Shaders (MPS) available")
except ImportError:
    print("❌ PyTorch not installed - cannot check CUDA status")

# Memory Check
print("\n💾 SYSTEM RESOURCES")
print("-" * 60)
try:
    import psutil
    mem = psutil.virtual_memory()
    print(f"Total RAM: {mem.total / 1024**3:.2f} GB")
    print(f"Available RAM: {mem.available / 1024**3:.2f} GB")
    print(f"RAM Usage: {mem.percent}%")
except ImportError:
    print("⚠️  psutil not installed - cannot check memory")

# Jupyter Check
print("\n📓 JUPYTER STATUS")
print("-" * 60)
try:
    result = subprocess.run(['jupyter', '--version'], capture_output=True, text=True)
    if result.returncode == 0:
        print("✅ Jupyter installed:")
        print(result.stdout)
    else:
        print("❌ Jupyter command failed")
except FileNotFoundError:
    print("❌ Jupyter not found in PATH")

# Summary
print("\n" + "=" * 60)
print("SUMMARY")
print("=" * 60)

if missing_packages:
    print(f"\n❌ Missing packages ({len(missing_packages)}):")
    print("   " + ", ".join(missing_packages))
    print("\n📝 To install missing packages:")
    print(f"   pip install {' '.join(missing_packages)}")
else:
    print("\n✅ All core packages installed!")

if python_version < (3, 9):
    print("\n⚠️  WARNING: Python version upgrade required (3.9+)")

print("\n💡 For detailed troubleshooting, visit:")
print("   https://github.com/PavanMudigonda/zero-to-ai/blob/main/00-course-setup/troubleshooting.md")
print("\n" + "=" * 60)

Save as diagnose_env.py and run:

python diagnose_env.py

Or download and run directly:

curl -fsSL https://raw.githubusercontent.com/PavanMudigonda/zero-to-ai/main/scripts/diagnose_env.py | python

Still stuck? Don’t hesitate to ask for help!

Troubleshooting Guide¶

� Quick Fixes (Most Common Issues)¶

📋 Table of Contents¶

🔍 Error Message Quick Reference¶

📊 Compatibility Matrix¶

Core Dependencies¶

Deep Learning Frameworks¶

GPU/CUDA Compatibility¶

Platform-Specific¶

Installation Issues¶

Problem: pip install fails with permission errors¶

Problem: conda command not found¶

Problem: UV installation fails¶

Environment Problems¶

Problem: Wrong Python version¶

Problem: Virtual environment not activating¶

Problem: Environment packages not found after activation¶

Jupyter Notebook Issues¶

Problem: Jupyter not found¶

Problem: Kernel not found or wrong kernel¶

Problem: Jupyter kernel keeps dying¶

Problem: Cannot open notebooks¶

Package Import Errors¶

Problem: ModuleNotFoundError: No module named 'X'¶

Problem: Import works in terminal but not in Jupyter¶

Problem: Package version conflicts¶

GPU/CUDA Issues¶

Problem: PyTorch not using GPU¶

Problem: CUDA out of memory¶

Problem: Multiple CUDA versions¶

Memory Issues¶

Problem: Jupyter notebook crashes with large datasets¶

Problem: RAM usage grows over time¶

Platform-Specific Issues¶

macOS¶

Problem: SSL certificate errors¶

Problem: M1/M2 compatibility issues¶

Windows¶

Problem: Long path names¶

Problem: Visual C++ redistributable missing¶

Linux¶

Problem: python3-dev missing¶

Common Error Messages¶

ImportError: DLL load failed¶

RuntimeError: CUDA error: out of memory¶

SyntaxError: invalid syntax¶

Getting More Help¶

When Asking for Help¶

Quick Diagnosis Script¶

🔧 One-Command Diagnostics¶

📝 Comprehensive Diagnostic Script¶

Problem: `pip install` fails with permission errors¶

Problem: `conda` command not found¶

Problem: `ModuleNotFoundError: No module named 'X'`¶

Problem: `python3-dev` missing¶

`ImportError: DLL load failed`¶

`RuntimeError: CUDA error: out of memory`¶

`SyntaxError: invalid syntax`¶