Installation Guide

This guide covers multiple ways to install SocialMapper depending on your needs and experience level.

Quick Installation

uv (Recommended)pip (Alternative)conda

uv pip install socialmapper

pip install socialmapper

# Add conda-forge channel if not already added
conda config --add channels conda-forge

# Install SocialMapper
conda install socialmapper

System Requirements

Python Version

• Python 3.11+ (minimum required)
• Python 3.12 (recommended for best performance)
• Python 3.13 (latest, fully supported)

Operating Systems

• ✅ Windows 10/11
• ✅ macOS 10.15+ (Intel and Apple Silicon)
• ✅ Linux (Ubuntu 20.04+, CentOS 8+, and others)

Hardware Recommendations

• RAM: 4GB minimum, 8GB+ recommended
• Storage: 1GB free space (for cache and outputs)
• Internet: Required for data downloads

Installation Options

Option 1: Standard Installation

For most users, the standard installation provides all core features:

uv pip install socialmapper

Option 2: Development Installation with Enhanced Features

For development work and extended functionality:

uv pip install socialmapper[dev]

This includes additional dependencies for: - 🔧 Development tools (testing, linting, formatting) - 📊 Enhanced analysis capabilities - 🎨 Rich terminal UI features

Option 3: Development Installation

For contributors and developers:

# Clone the repository
git clone https://github.com/mihiarc/socialmapper.git
cd socialmapper

# Install in development mode with all dependencies
uv pip install -e .[dev]

Option 4: Minimal Installation

Note: The [minimal] extra is not currently available. The standard installation already provides a lightweight experience.

Dependency Management

Using uv (Recommended)

According to a memory from a past conversation, you should use 'uv' as the package management tool for installing and managing Python dependencies in this project instead of pip.

# Install uv
pip install uv

# Create a new project with SocialMapper
uv init my-socialmapper-project
cd my-socialmapper-project
uv add socialmapper

# Or add to existing project
uv add socialmapper

Using pip with virtual environments

# Create virtual environment
python -m venv socialmapper-env

# Activate (Windows)
socialmapper-env\Scripts\activate

# Activate (macOS/Linux)
source socialmapper-env/bin/activate

# Install SocialMapper
pip install socialmapper

Verify Installation

Test your installation with these commands:

# Check version
uv run python -c "import socialmapper; print(socialmapper.__version__)"

# Run help command
uv run socialmapper --help

# Quick test (requires internet)
uv run python -c "from socialmapper import run_socialmapper; print('✅ Installation successful!')"

Optional: API Keys

While SocialMapper works without API keys, some features are enhanced with them:

Census Bureau API Key (Recommended)

• Benefit: Faster census data downloads
• Get key: Census API Registration
• Setup: export CENSUS_API_KEY="your_key_here"

Google Maps API Key (Optional)

• Benefit: Enhanced geocoding accuracy
• Get key: Google Cloud Console
• Setup: export GOOGLE_MAPS_API_KEY="your_key_here"

Common Installation Issues

Issue: "No module named 'socialmapper'"

Solution:

# Ensure you're in the right environment
which python
pip list | grep socialmapper

# Reinstall if needed
pip uninstall socialmapper
pip install socialmapper

Issue: Dependency conflicts

Solution: Use a fresh virtual environment:

python -m venv fresh-env
source fresh-env/bin/activate  # or fresh-env\Scripts\activate on Windows
pip install socialmapper

Issue: Network/SSL errors

Solution: Update certificates and try again:

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

# Or use trusted hosts
pip install --trusted-host pypi.org --trusted-host pypi.python.org socialmapper

Issue: Permission errors (Linux/macOS)

Solution: Use user installation:

pip install --user socialmapper

Issue: Missing system dependencies (Linux)

Solution: Install system packages:

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

# CentOS/RHEL
sudo yum install python3-devel python3-pip gcc

Platform-Specific Notes

Windows

• Use Command Prompt or PowerShell (avoid Git Bash for installation)
• Consider Windows Subsystem for Linux (WSL) for a Linux-like experience
• Visual Studio Build Tools may be needed for some dependencies

macOS

• Xcode Command Line Tools required: xcode-select --install
• Homebrew recommended for Python management: brew install python
• Apple Silicon (M1/M2): All dependencies are compatible

Linux

• Most distributions include Python, but you may need python3-pip
• GDAL and spatial libraries are included in the package
• Build tools (gcc, make) may be required

Next Steps

After successful installation:

1. 📖 Read the Quick Start Guide
2. 🎯 Explore the Examples
3. 💻 Learn about Finding Places
4. 🔧 Get a Census API key (optional)

Getting Help

If you encounter issues:

1. 📚 Check this documentation
2. 🔍 Search GitHub Issues
3. 🐛 Report new issues with:
4. Your Python version (python --version)
5. Your OS and version
6. Complete error messages
7. Installation method used

---

Ready to start? Continue to the Quick Start Guide!