Creating a Diagnostic Script #

Step 2: Package Installation Verification #

Verify that packages are actually installed and accessible:

def verify_package_installation(package_name):
    """Comprehensive package installation verification"""
    import subprocess
    import sys
    
    print(f"=== VERIFYING PACKAGE: {package_name} ===\n")
    
    # Test 1: Can we import it?
    try:
        module = __import__(package_name)
        print(f"✓ Package '{package_name}' can be imported")
        
        # Get package location
        if hasattr(module, '__file__'):
            print(f"  Location: {module.__file__}")
        elif hasattr(module, '__path__'):
            print(f"  Package path: {list(module.__path__)}")
        else:
            print(f"  Built-in module")
            
    except ImportError as e:
        print(f"✗ Package '{package_name}' cannot be imported")
        print(f"  Error: {e}")
    
    # Test 2: Is it installed via pip?
    try:
        result = subprocess.run(
            [sys.executable, '-m', 'pip', 'show', package_name],
            capture_output=True, text=True, check=False
        )
        
        if result.returncode == 0:
            print(f"\\n✓ Package '{package_name}' is installed via pip")
            # Extract key information
            for line in result.stdout.split('\\n'):
                if line.startswith(('Location:', 'Version:', 'Requires:')):
                    print(f"  {line}")
        else:
            print(f"\\n- Package '{package_name}' not found via pip show")
            
    except Exception as e:
        print(f"\\nError running pip show: {e}")
    
    # Test 3: Check in pip list
    try:
        result = subprocess.run(
            [sys.executable, '-m', 'pip', 'list'],
            capture_output=True, text=True, check=True
        )
        
        installed_packages = result.stdout.lower()
        if package_name.lower() in installed_packages:
            print(f"\\n✓ Package '{package_name}' appears in pip list")
        else:
            print(f"\\n- Package '{package_name}' not found in pip list")
            
    except Exception as e:
        print(f"\\nError running pip list: {e}")

Step 3: Environment Synchronization #

The most critical step is ensuring pip and Python use the same environment:

Step 4: Virtual Environment Troubleshooting #

Virtual environments are often the source of module import issues:

def troubleshoot_virtual_environments():
    """Complete virtual environment troubleshooting guide"""
    
    print("=== VIRTUAL ENVIRONMENT TROUBLESHOOTING ===\n")
    
    # Check current state
    import os
    import sys
    
    venv_path = os.environ.get('VIRTUAL_ENV')
    
    print("1. VIRTUAL ENVIRONMENT STATUS")
    if venv_path:
        print(f"   ✓ VIRTUAL_ENV set to: {venv_path}")
        
        # Check if Python executable is actually from this venv
        if venv_path in sys.executable:
            print("   ✓ Python executable matches VIRTUAL_ENV")
        else:
            print("   ⚠ Python executable doesn't match VIRTUAL_ENV!")
            print(f"      Expected: {venv_path}/bin/python")
            print(f"      Actual: {sys.executable}")
            
    else:
        print("   - No virtual environment detected")
        print("   - Using system Python installation")
    
    # Provide troubleshooting steps
    print("\\n2. COMMON VIRTUAL ENVIRONMENT FIXES")
    
    troubleshooting_steps = [
        ("Deactivate and reactivate", [
            "deactivate  # If currently in venv",
            "source venv/bin/activate  # Linux/Mac",
            "# or venv\\\\Scripts\\\\activate  # Windows"
        ]),
        
        ("Create fresh virtual environment", [
            "python -m venv new_project_env",
            "source new_project_env/bin/activate",
            "python -m pip install --upgrade pip",
            "python -m pip install -r requirements.txt"
        ]),
        
        ("Check virtual environment integrity", [
            "which python  # Should show venv path",
            "which pip     # Should show venv path",
            "python -c 'import sys; print(sys.prefix)'"
        ]),
        
        ("Fix PATH issues", [
            "echo $VIRTUAL_ENV",
            "echo $PATH | grep $VIRTUAL_ENV",
            "# If venv not in PATH, reactivate environment"
        ])
    ]
    
    for step_name, commands in troubleshooting_steps:
        print(f"\\n   {step_name}:")
        for cmd in commands:
            print(f"     {cmd}")
    
    return venv_path

# Virtual environment diagnostic
current_venv = troubleshoot_virtual_environments()

Step 5: IDE and Jupyter Integration #

IDEs and Jupyter notebooks often use different Python interpreters:

Step 6: Advanced Package Installation Strategies #

Sometimes standard installation methods fail. Here are advanced approaches:

def advanced_installation_strategies():
    """Advanced package installation and troubleshooting"""
    
    print("=== ADVANCED INSTALLATION STRATEGIES ===\n")
    
    strategies = [
        {
            "Strategy": "Force Reinstallation",
            "When": "Package partially corrupted or wrong version cached",
            "Commands": [
                "python -m pip uninstall package_name -y",
                "python -m pip install --no-cache-dir package_name",
                "# or",
                "python -m pip install --force-reinstall package_name"
            ]
        },
        
        {
            "Strategy": "User Space Installation", 
            "When": "System permissions prevent global installation",
            "Commands": [
                "python -m pip install --user package_name",
                "# Package installs to ~/.local/lib/python*/site-packages"
            ]
        },
        
        {
            "Strategy": "Development Installation",
            "When": "Installing from source code or git repository",
            "Commands": [
                "python -m pip install -e /path/to/package",
                "python -m pip install git+https://github.com/user/repo.git",
                "python -m pip install -e git+https://github.com/user/repo.git#egg=package"
            ]
        },
        
        {
            "Strategy": "Dependency Resolution",
            "When": "Complex dependency conflicts",
            "Commands": [
                "python -m pip install --upgrade pip setuptools wheel",
                "python -m pip install package_name --upgrade --force-reinstall --no-deps",
                "python -m pip install package_name --no-deps"
            ]
        },
        
        {
            "Strategy": "Alternative Installation Methods",
            "When": "Pip installation consistently fails",
            "Commands": [
                "# Using conda instead of pip",
                "conda install package_name",
                "",
                "# Using system package manager",
                "sudo apt install python3-package_name  # Ubuntu",
                "brew install package_name             # macOS"
            ]
        }
    ]
    
    for strategy in strategies:
        print(f"{strategy['Strategy']}:")
        print(f"  When to use: {strategy['When']}")
        print("  Commands:")
        for cmd in strategy['Commands']:
            if cmd.strip():  # Skip empty lines
                print(f"    {cmd}")
        print()
    
    return "Advanced strategies documented"

Common Package-Specific Issues #

Import Name vs Package Name Mismatches #

Many packages have different installation and import names:

Automated Troubleshooting Script #

Let's create a comprehensive automated troubleshooting script:

#!/usr/bin/env python3
"""
Comprehensive Python Module Import Troubleshooter
Automatically diagnoses and suggests fixes for module import issues
"""

import sys
import os
import subprocess
import site
from pathlib import Path

class ModuleImportTroubleshooter:
    def __init__(self, package_name):
        self.package_name = package_name
        self.python_executable = sys.executable
        self.issues_found = []
        self.solutions = []
        
    def run_full_diagnosis(self):
        """Run complete diagnostic and provide solutions"""
        print(f"=== TROUBLESHOOTING MODULE: {self.package_name} ===\n")
        
        self._check_basic_environment()
        self._check_package_installation()
        self._check_import_capability()
        self._check_environment_consistency()
        self._check_common_issues()
        
        self._provide_solutions()
        
    def _check_basic_environment(self):
        """Check basic Python environment setup"""
        print("1. BASIC ENVIRONMENT CHECK")
        
        print(f"   Python: {sys.version.split()[0]} at {self.python_executable}")
        
        venv = os.environ.get('VIRTUAL_ENV')
        if venv:
            print(f"   Virtual Environment: {venv}")
            if venv not in self.python_executable:
                self.issues_found.append("Python executable not from active virtual environment")
        else:
            print("   Virtual Environment: Not active")
            
    def _check_package_installation(self):
        """Check if package is properly installed"""
        print("\n2. PACKAGE INSTALLATION CHECK")
        
        try:
            result = subprocess.run(
                [sys.executable, '-m', 'pip', 'show', self.package_name],
                capture_output=True, text=True, check=True
            )
            print(f"   ✓ Package '{self.package_name}' is installed")
            
            # Extract installation location
            for line in result.stdout.split('\n'):
                if line.startswith('Location:'):
                    location = line.split('Location: ')[1]
                    print(f"   Location: {location}")
                    break
                    
        except subprocess.CalledProcessError:
            print(f"   ✗ Package '{self.package_name}' not found via pip")
            self.issues_found.append("Package not installed via pip")
            
    def _check_import_capability(self):
        """Test if package can be imported"""
        print("\n3. IMPORT CAPABILITY TEST")
        
        # Try importing with various name variations
        import_variations = [
            self.package_name,
            self.package_name.replace('-', '_'),
            self.package_name.replace('_', '-'),
            self.package_name.split('-')[0]
        ]
        
        successful_import = None
        for variant in import_variations:
            try:
                module = __import__(variant)
                print(f"   ✓ Successfully imported as '{variant}'")
                if hasattr(module, '__file__'):
                    print(f"   Module location: {module.__file__}")
                successful_import = variant
                break
            except ImportError:
                continue
                
        if not successful_import:
            print(f"   ✗ Could not import '{self.package_name}' with any variation")
            self.issues_found.append("Package cannot be imported")
            
    def _check_environment_consistency(self):
        """Check Python and pip environment consistency"""
        print("\n4. ENVIRONMENT CONSISTENCY CHECK")
        
        try:
            pip_version_output = subprocess.run(
                [sys.executable, '-m', 'pip', '--version'],
                capture_output=True, text=True, check=True
            ).stdout
            
            pip_python_path = pip_version_output.split('(python ')[1].split(')')[0]
            current_python_version = f"{sys.version_info.major}.{sys.version_info.minor}"
            
            if current_python_version in pip_python_path:
                print("   ✓ Python and pip versions are consistent")
            else:
                print("   ⚠ Python and pip version mismatch detected")
                self.issues_found.append("Python and pip version mismatch")
                
        except Exception as e:
            print(f"   ⚠ Could not verify pip consistency: {e}")
            
    def _check_common_issues(self):
        """Check for common problematic scenarios"""
        print("\n5. COMMON ISSUES CHECK")
        
        # Check for multiple Python installations
        python_executables = []
        common_paths = ['/usr/bin/python', '/usr/bin/python3', '/usr/local/bin/python3']
        
        for path in common_paths:
            if os.path.exists(path) and path != self.python_executable:
                python_executables.append(path)
                
        if python_executables:
            print(f"   ⚠ Multiple Python installations detected:")
            for path in python_executables:
                print(f"      {path}")
            self.issues_found.append("Multiple Python installations")
            
        # Check site-packages accessibility
        try:
            site_packages = site.getsitepackages()
            for path in site_packages:
                if not os.access(path, os.R_OK):
                    print(f"   ⚠ Site-packages not readable: {path}")
                    self.issues_found.append("Site-packages permission issue")
        except:
            pass
            
    def _provide_solutions(self):
        """Provide targeted solutions based on issues found"""
        print(f"\n=== SOLUTIONS FOR {len(self.issues_found)} ISSUES FOUND ===\n")
        
        if not self.issues_found:
            print("✓ No issues detected! Package should be importable.")
            return
            
        solution_map = {
            "Package not installed via pip": [
                f"Install the package: {self.python_executable} -m pip install {self.package_name}",
                f"Or try with --user flag: {self.python_executable} -m pip install --user {self.package_name}"
            ],
            
            "Package cannot be imported": [
                f"Check package documentation for correct import name",
                f"Try: {self.python_executable} -c \"import {self.package_name.replace('-', '_')}\"",
                f"Search installed packages: {self.python_executable} -m pip list | grep -i {self.package_name}"
            ],
            
            "Python executable not from active virtual environment": [
                "Deactivate and reactivate your virtual environment:",
                "  deactivate",
                "  source venv/bin/activate  # or venv\\Scripts\\activate on Windows"
            ],
            
            "Python and pip version mismatch": [
                f"Use explicit Python command: {self.python_executable} -m pip install {self.package_name}",
                "Avoid using bare 'pip' command"
            ],
            
            "Multiple Python installations": [
                f"Always use full path: {self.python_executable} -m pip install ...",
                "Consider using virtual environments to avoid conflicts"
            ],
            
            "Site-packages permission issue": [
                f"Try user installation: {self.python_executable} -m pip install --user {self.package_name}",
                "Or use virtual environment to avoid system permission issues"
            ]
        }
        
        for i, issue in enumerate(self.issues_found, 1):
            print(f"{i}. ISSUE: {issue}")
            if issue in solution_map:
                print("   SOLUTIONS:")
                for solution in solution_map[issue]:
                    print(f"     {solution}")
            print()
            
        # General recommendations
        print("GENERAL RECOMMENDATIONS:")
        print(f"  • Always use: {self.python_executable} -m pip install <package>")
        print("  • Use virtual environments for project isolation")
        print("  • Check package documentation for correct import names")
        print("  • Restart your IDE/terminal after installation")

# Usage example:
if __name__ == "__main__":
    import sys
    package_name = sys.argv[1] if len(sys.argv) > 1 else "requests"
    troubleshooter = ModuleImportTroubleshooter(package_name)
    troubleshooter.run_full_diagnosis()

Prevention Best Practices #

Project Environment Setup #

Create a standardized project setup routine:

#!/bin/bash
# setup_python_project.sh - Standard Python project setup

PROJECT_NAME=${1:-"my_python_project"}

echo "Setting up Python project: $PROJECT_NAME"

# Create project directory
mkdir -p $PROJECT_NAME
cd $PROJECT_NAME

# Create virtual environment
echo "Creating virtual environment..."
python3 -m venv venv

# Activate virtual environment
echo "Activating virtual environment..."
source venv/bin/activate

# Upgrade pip
echo "Upgrading pip..."
python -m pip install --upgrade pip setuptools wheel

# Create project structure
echo "Creating project structure..."
mkdir -p src tests docs

# Create requirements file template
cat > requirements.txt << EOF
# Core dependencies
requests>=2.28.0
numpy>=1.24.0

# Development dependencies (install with: pip install -r requirements-dev.txt)
# pytest>=7.0.0
# black>=22.0.0
# flake8>=5.0.0
EOF

# Create .gitignore
cat > .gitignore << EOF
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
venv/
.env
.DS_Store
EOF

# Create project README
cat > README.md << EOF
# $PROJECT_NAME

## Setup

\`\`\`bash
# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\\Scripts\\activate  # Windows

# Install dependencies
python -m pip install -r requirements.txt
\`\`\`

## Usage

\`\`\`python
# Your code here
\`\`\`
EOF

echo "Project setup complete!"
echo "To activate: source venv/bin/activate"
echo "To install dependencies: python -m pip install -r requirements.txt"

Summary and Key Takeaways #

After completing this comprehensive tutorial, you should understand:

1. Root Causes: Module import failures typically stem from environment mismatches, not package installation failures
2. Diagnostic Approach: Systematic diagnosis saves time compared to random troubleshooting attempts
3. Prevention: Using python -m pip install instead of bare pip install prevents most issues
4. Environment Management: Virtual environments are essential for reproducible Python development
5. IDE Integration: Configure IDEs to use the correct Python interpreter
6. Documentation: Always check package documentation for correct import syntax

By following this comprehensive tutorial, you now have the knowledge and tools to systematically diagnose and fix Python module not found errors despite installing with pip troubleshooting. The key is understanding Python's environment system and maintaining consistency between your Python interpreter and pip installation commands.