Installation Troubleshooting¶

This guide helps you troubleshoot and resolve common installation issues with REROUTE.

Pre-Installation Checklist¶

Before installing REROUTE, ensure you have:

[ ] Python 3.8 or higher installed
[ ] pip or uv package manager installed
[ ] Virtual environment created (recommended)
[ ] Write permissions for the installation directory

Python Version Issues¶

Check Your Python Version¶

python --version
# or
python3 --version

Required: Python 3.8 or higher

Issue: Python Too Old¶

Symptoms:

ERROR: Package 'reroute' requires a different Python version

Solution:

Install Python 3.8+
Windows: Download from python.org
macOS: brew install python@3.11
Linux: sudo apt-get install python3.11 (Ubuntu/Debian)
Use Python Version Manager (Recommended)

pyenv (macOS/Linux):

brew install pyenv
pyenv install 3.11
pyenv global 3.11

Package Manager Issues¶

Issue: pip Not Found¶

Symptoms:

bash: pip: command not found

Solution:

python -m ensurepip --upgrade

Issue: pip Too Old¶

Symptoms:

WARNING: You are using pip version X; upgrade to use newer features

Solution:

python -m pip install --upgrade pip

Issue: Using uv (Recommended)¶

Why uv? uv is 10-100x faster than pip.

Install uv:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Use uv for installation:

uv pip install reroute[fastapi]

Virtual Environment Issues¶

Why Use Virtual Environments?¶

Virtual environments isolate your project dependencies, preventing conflicts between projects.

Creating a Virtual Environment¶

Using venv (built-in):

# Create
python -m venv venv

# Activate (macOS/Linux)
source venv/bin/activate

# Activate (Windows)
venv\Scripts\activate

# Deactivate
deactivate

Using uv (faster):

# Create
uv venv

# Activate (macOS/Linux)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

Installation Errors¶

Issue: Permission Denied¶

Symptoms:

ERROR: Could not install packages due to an EnvironmentError: [Errno 13] Permission denied

Solution:

Option 1: Use virtual environment (Recommended)

python -m venv venv
source venv/bin/activate  # macOS/Linux
# or
venv\Scripts\activate  # Windows
pip install reroute

Option 2: Use --user flag

pip install --user reroute

Issue: Network/Proxy Issues¶

Symptoms:

ERROR: Could not find a version that satisfies the requirement reroute

Solution:

Check internet connection:
```
ping pypi.org
```

Use PyPI mirror:

pip install -i https://pypi.org/simple reroute

Dependency Issues¶

Issue: FastAPI Not Installing¶

Symptoms:

ERROR: No matching distribution found for fastapi

Solution:

Install with extras:

pip install reroute[fastapi]

Or install dependencies separately:

pip install fastapi uvicorn
pip install reroute

OS-Specific Guides¶

Windows¶

Common Issues:

Path too long error:

# Install to shorter path
cd D:\
mkdir projects
cd projects
pip install reroute

Python not in PATH:
Add Python to PATH during installation
Or use full path: C:\Python311\python.exe -m pip install reroute

macOS¶

Common Issues:

Xcode command line tools missing:
```
xcode-select --install
```

Homebrew Python vs system Python:

# Use Homebrew Python
brew install python@3.11
/opt/homebrew/bin/python3 -m pip install reroute

Linux (Ubuntu/Debian)¶

Common Issues:

Missing build dependencies:

sudo apt-get update
sudo apt-get install python3-dev python3-pip build-essential

System Python restrictions:

# Always use virtual environment
python3 -m venv venv
source venv/bin/activate
pip install reroute

Port Conflict Issues¶

Issue: Port Already in Use¶

Symptoms:

OSError: [Errno 98] Address already in use

Solution:

Option 1: Use different port

# config.py
class AppConfig(Config):
    PORT = 8080  # Change from default 7376

Option 2: Kill process using port

Windows:

netstat -ano | findstr :7376
taskkill /PID <process_id> /F

macOS/Linux:

lsof -ti:7376 | xargs kill -9

Verification Steps¶

After installation, verify everything works:

1. Check Installation¶

python -c "import reroute; print(reroute.__version__)"

Expected output: Current version number

2. Check CLI¶

reroute --version

Expected output: Version information

3. Create Test Project¶

reroute init test-app --framework fastapi
cd test-app
python main.py

Expected: Server starts successfully

Still Having Issues?¶

Check Python path:

which python  # macOS/Linux
where python  # Windows

Clear pip cache:
```
pip cache purge
```

Try fresh virtual environment:

rm -rf venv
python -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install reroute

Getting Help¶

If you're still stuck:

Check existing issues: GitHub Issues
Create minimal reproduction: Isolate the problem

Provide system information:

python --version
pip --version
uname -a  # macOS/Linux
systeminfo  # Windows

File new issue: Include error messages and system information

Quick Reference¶

Problem	Solution
Python too old	Install Python 3.8+
Permission denied	Use virtual environment
Network error	Check internet/proxy
Port in use	Change port or kill process
Import error	Reinstall in virtual environment

Next Steps¶

Once installation is successful:

Quick Start Guide - Build your first API
Hello World Tutorial - Learn by doing
User Guide - Deep dive into features