Skip to content

Installation Guide

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

Quick Installation

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

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:

  • 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!