---
title: "Windows Setup"
description: "Complete guide for setting up TraceRTM development environment on Windows"
---

# Windows Development Setup

Complete guide for setting up TraceRTM on Windows 10/11 using either WSL2 (recommended) or native Windows.

## Overview

TraceRTM can be run on Windows in two ways:

1. **WSL2 (Recommended)**: Best compatibility, Linux-like environment, easier dependency management
2. **Native Windows**: Direct Windows installation, better IDE integration with Windows tools

This guide covers both approaches comprehensively.

## Prerequisites

### Windows Requirements

- **Operating System**: Windows 10 version 2004+ (Build 19041+) or Windows 11
- **RAM**: Minimum 8GB, 16GB recommended for development
- **Disk Space**: At least 20GB free space
- **Processor**: 64-bit processor with virtualization support (for WSL2)

### Administrator Access

You'll need administrator privileges for:
- Enabling WSL2 features
- Installing software via package managers
- Configuring Windows features
- Setting up PostgreSQL and Redis services

---

## Option 1: WSL2 Setup (Recommended)

WSL2 provides the best development experience on Windows with native Linux performance.

### Step 1: Enable WSL2

Open PowerShell as Administrator and run:

```powershell
# Enable WSL and Virtual Machine Platform
wsl --install

# Or manually enable features
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# Set WSL 2 as default
wsl --set-default-version 2
```

**Restart your computer** after enabling WSL2.

### Step 2: Install Ubuntu on WSL2

```powershell
# Install Ubuntu 22.04 LTS (recommended)
wsl --install -d Ubuntu-22.04

# Or list available distributions
wsl --list --online

# After installation, launch Ubuntu
wsl
```

Set up your Ubuntu user when prompted (username and password).

### Step 3: Update Ubuntu System

Inside WSL2 Ubuntu terminal:

```bash
# Update package lists
sudo apt update && sudo apt upgrade -y

# Install essential build tools
sudo apt install -y build-essential curl wget git
```

### Step 4: Install Python 3.12+

Ubuntu 22.04 ships with Python 3.10, so we'll install Python 3.12:

```bash
# Add deadsnakes PPA for newer Python versions
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update

# Install Python 3.12 and required packages
sudo apt install -y python3.12 python3.12-venv python3.12-dev python3-pip

# Set Python 3.12 as default (optional)
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1

# Verify installation
python3.12 --version  # Should show Python 3.12.x
```

### Step 5: Install Node.js 20+

```bash
# Install Node.js via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Verify installation
node --version   # Should show v20.x.x
npm --version    # Should show v10.x.x

# Optional: Install pnpm (recommended for TraceRTM frontend)
npm install -g pnpm
pnpm --version
```

### Step 6: Install PostgreSQL

```bash
# Install PostgreSQL 14+
sudo apt install -y postgresql postgresql-contrib

# Start PostgreSQL service
sudo service postgresql start

# Create database and user
sudo -u postgres psql << EOF
CREATE DATABASE tracertm;
CREATE USER tracertm_user WITH PASSWORD 'tracertm_dev_password';
GRANT ALL PRIVILEGES ON DATABASE tracertm TO tracertm_user;
ALTER DATABASE tracertm OWNER TO tracertm_user;
\q
EOF

# Verify PostgreSQL is running
sudo service postgresql status
```

**Auto-start PostgreSQL on WSL startup:**

Add to `~/.bashrc`:

```bash
# Auto-start PostgreSQL
if ! service postgresql status > /dev/null 2>&1; then
    sudo service postgresql start
fi
```

### Step 7: Install Redis

```bash
# Install Redis
sudo apt install -y redis-server

# Start Redis service
sudo service redis-server start

# Verify Redis is running
redis-cli ping  # Should return PONG

# Auto-start Redis on WSL startup
# Add to ~/.bashrc:
if ! service redis-server status > /dev/null 2>&1; then
    sudo service redis-server start
fi
```

### Step 8: Clone Repository

```bash
# Create development directory
mkdir -p ~/dev
cd ~/dev

# Clone TraceRTM repository
git clone https://github.com/yourusername/tracertm.git
cd tracertm
```

### Step 9: Setup Python Environment

```bash
# Create virtual environment with Python 3.12
python3.12 -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install TraceRTM with development dependencies
pip install -e ".[dev]"

# Verify installation
rtm --version
```

### Step 10: Configure Environment Variables

```bash
# Copy example environment file
cp .env.example .env

# Edit .env file
nano .env
```

Update `.env` with your settings:

```bash
# Database Configuration (PostgreSQL)
TRACERTM_DATABASE__URL=postgresql://tracertm_user:tracertm_dev_password@localhost:5432/tracertm
TRACERTM_DATABASE__ECHO=false
TRACERTM_DATABASE__POOL_SIZE=10

# Development Settings
TRACERTM_LOG_LEVEL=DEBUG
TRACERTM_ENABLE_CACHE=true
```

### Step 11: Initialize Database

```bash
# Ensure virtual environment is activated
source .venv/bin/activate

# Initialize database schema (if migrations exist)
# alembic upgrade head

# Or run initialization script
rtm init
```

### Step 12: Run Development Server

```bash
# Ensure virtual environment is activated
source .venv/bin/activate

# Run the TUI application
rtm tui

# Or start the API server (if available)
# rtm serve
```

### Step 13: Setup IDE (VS Code with WSL)

**Install VS Code on Windows:**

1. Download from https://code.visualstudio.com/
2. Install with default options

**Install WSL Extension:**

1. Open VS Code
2. Install "Remote - WSL" extension (ms-vscode-remote.remote-wsl)
3. Click "Open a Remote Window" (bottom-left green icon)
4. Select "Connect to WSL"

**Open Project in WSL:**

```bash
# From WSL terminal in project directory
code .
```

**Recommended VS Code Extensions for WSL:**

- Python (ms-python.python)
- Pylance (ms-python.vscode-pylance)
- Python Debugger (ms-python.debugpy)
- Ruff (charliermarsh.ruff)
- SQLTools (mtxr.sqltools)
- PostgreSQL (ckolkman.vscode-postgres)

**Configure Python Interpreter:**

1. Open Command Palette (`Ctrl+Shift+P`)
2. Select "Python: Select Interpreter"
3. Choose `.venv/bin/python3.12`

---

## Option 2: Native Windows Setup

Native Windows setup without WSL2.

### Step 1: Install Git for Windows

Download and install from: https://git-scm.com/download/win

**Installation options:**
- Use recommended defaults
- Select "Git from the command line and also from 3rd-party software"
- Use bundled OpenSSH
- Use Windows Secure Channel library

### Step 2: Install Python 3.12+

**Download Python:**

Visit https://www.python.org/downloads/ and download Python 3.12+

**Installation:**

1. Run installer
2. **Check "Add Python to PATH"** (important!)
3. Select "Customize installation"
4. Ensure "pip" is selected
5. Enable "Install for all users" (optional)
6. Click "Install"

**Verify installation:**

```powershell
# Open new PowerShell window
python --version   # Should show Python 3.12.x
pip --version
```

### Step 3: Install Node.js

**Download Node.js:**

Visit https://nodejs.org/ and download the LTS version (20.x)

**Installation:**

1. Run installer with default options
2. Restart PowerShell after installation

**Verify installation:**

```powershell
node --version   # Should show v20.x.x
npm --version
```

**Optional: Install pnpm:**

```powershell
npm install -g pnpm
```

### Step 4: Install PostgreSQL

**Download PostgreSQL:**

Visit https://www.postgresql.org/download/windows/ and download PostgreSQL 14+

**Installation:**

1. Run installer
2. Set password for `postgres` user (remember this!)
3. Port: 5432 (default)
4. Locale: Default
5. Complete installation

**Create Database:**

Open pgAdmin (installed with PostgreSQL):

1. Connect to PostgreSQL server
2. Right-click "Databases" → "Create" → "Database"
3. Name: `tracertm`
4. Owner: postgres (or create dedicated user)
5. Save

**Or use command line:**

```powershell
# Navigate to PostgreSQL bin directory
cd "C:\Program Files\PostgreSQL\14\bin"

# Create database
.\psql.exe -U postgres -c "CREATE DATABASE tracertm;"
.\psql.exe -U postgres -c "CREATE USER tracertm_user WITH PASSWORD 'tracertm_dev_password';"
.\psql.exe -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE tracertm TO tracertm_user;"
```

### Step 5: Install Redis (Windows)

**Option A: Use Memurai (Redis-compatible for Windows)**

1. Download from https://www.memurai.com/
2. Install with default options
3. Service runs automatically

**Option B: Use Redis via WSL (if WSL is installed)**

```powershell
wsl -d Ubuntu-22.04
sudo apt install redis-server
sudo service redis-server start
```

**Option C: Use Docker Desktop**

```powershell
docker run -d -p 6379:6379 redis:latest
```

### Step 6: Clone Repository

```powershell
# Create development directory
New-Item -ItemType Directory -Path C:\dev -Force
cd C:\dev

# Clone repository
git clone https://github.com/yourusername/tracertm.git
cd tracertm
```

### Step 7: Setup Python Virtual Environment

```powershell
# Create virtual environment
python -m venv .venv

# Activate virtual environment (PowerShell)
.\.venv\Scripts\Activate.ps1

# If you get execution policy error:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or use Command Prompt:
# .\.venv\Scripts\activate.bat

# Upgrade pip
python -m pip install --upgrade pip

# Install TraceRTM with development dependencies
pip install -e ".[dev]"

# Verify installation
rtm --version
```

### Step 8: Configure Environment Variables

```powershell
# Copy example environment file
Copy-Item .env.example .env

# Edit .env file with notepad
notepad .env
```

Update `.env`:

```bash
# Database Configuration (PostgreSQL on Windows)
TRACERTM_DATABASE__URL=postgresql://tracertm_user:tracertm_dev_password@localhost:5432/tracertm
TRACERTM_DATABASE__ECHO=false
TRACERTM_DATABASE__POOL_SIZE=10

# Development Settings
TRACERTM_LOG_LEVEL=DEBUG
TRACERTM_ENABLE_CACHE=true
```

### Step 9: Initialize Database

```powershell
# Ensure virtual environment is activated
.\.venv\Scripts\Activate.ps1

# Initialize database
rtm init
```

### Step 10: Run Development Server

```powershell
# Ensure virtual environment is activated
.\.venv\Scripts\Activate.ps1

# Run TUI application
rtm tui

# Or start API server
# rtm serve
```

### Step 11: Setup IDE (PyCharm or VS Code)

**PyCharm Professional (recommended for Windows):**

1. Download from https://www.jetbrains.com/pycharm/
2. Open project directory
3. Configure interpreter:
   - File → Settings → Project → Python Interpreter
   - Add Interpreter → Existing Environment
   - Select `.venv\Scripts\python.exe`
4. Install recommended plugins:
   - Database Tools and SQL
   - .env files support

**VS Code (free alternative):**

1. Download from https://code.visualstudio.com/
2. Open project directory
3. Install extensions:
   - Python (ms-python.python)
   - Pylance (ms-python.vscode-pylance)
   - Ruff (charliermarsh.ruff)
4. Configure Python interpreter:
   - Press `Ctrl+Shift+P`
   - Select "Python: Select Interpreter"
   - Choose `.venv\Scripts\python.exe`

---

## Common Windows Development Issues

### Issue 1: PowerShell Execution Policy

**Problem:** Cannot activate virtual environment due to execution policy.

**Solution:**

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### Issue 2: Long Path Names

**Problem:** File paths exceed Windows MAX_PATH limit (260 characters).

**Solution:**

Enable long paths in Windows:

```powershell
# Run as Administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
```

### Issue 3: PostgreSQL Connection Issues

**Problem:** Cannot connect to PostgreSQL.

**Solutions:**

```powershell
# Check PostgreSQL service is running
Get-Service -Name postgresql*

# Start service if stopped
Start-Service postgresql-x64-14  # Adjust version number

# Check connection
& "C:\Program Files\PostgreSQL\14\bin\psql.exe" -U postgres -c "SELECT version();"
```

### Issue 4: Redis Not Available on Windows

**Problem:** Redis doesn't have official Windows support.

**Solutions:**

1. Use Memurai (Redis-compatible): https://www.memurai.com/
2. Use WSL2 with Redis (recommended)
3. Use Docker Desktop with Redis container
4. Use Redis Cloud (for development): https://redis.com/try-free/

### Issue 5: Python Version Conflicts

**Problem:** Multiple Python versions installed.

**Solution:**

```powershell
# Use Python Launcher to specify version
py -3.12 --version
py -3.12 -m venv .venv

# Or use full path
C:\Python312\python.exe --version
```

### Issue 6: Git Line Endings

**Problem:** Line ending conflicts between Windows (CRLF) and Linux (LF).

**Solution:**

```bash
# Configure Git to handle line endings
git config --global core.autocrlf true

# Or for repository-specific
git config core.autocrlf true
```

### Issue 7: Permission Errors

**Problem:** Permission denied errors when installing packages or running commands.

**Solutions:**

```powershell
# Run PowerShell as Administrator for system-wide changes

# Or install packages for current user only
pip install --user package_name

# Fix npm permissions
npm config set prefix "%APPDATA%\npm"
```

### Issue 8: Slow File System Performance

**Problem:** WSL2 has slow file access when accessing Windows files.

**Solution:**

- Store project files in WSL2 filesystem (`~/dev/`) not Windows (`/mnt/c/`)
- Access WSL files from Windows: `\\wsl$\Ubuntu-22.04\home\username\dev\`

### Issue 9: Port Already in Use

**Problem:** PostgreSQL or Redis port already occupied.

**Solution:**

```powershell
# Find process using port 5432 (PostgreSQL)
netstat -ano | findstr :5432

# Kill process (replace PID)
taskkill /PID <process_id> /F

# Or change port in connection string
# postgresql://user:pass@localhost:5433/tracertm
```

### Issue 10: Textual TUI Display Issues

**Problem:** Terminal doesn't display Textual TUI correctly.

**Solutions:**

1. Use Windows Terminal (recommended):
   ```powershell
   winget install Microsoft.WindowsTerminal
   ```

2. Update PowerShell to latest version:
   ```powershell
   winget install Microsoft.PowerShell
   ```

3. Use WSL2 terminal instead of Windows Command Prompt

---

## Testing Your Setup

After completing setup, verify everything works:

```bash
# Activate virtual environment
# WSL/Linux:
source .venv/bin/activate
# Windows:
.\.venv\Scripts\Activate.ps1

# Run tests
pytest tests/ -v

# Check database connection
rtm db check

# Run TUI application
rtm tui

# Check version
rtm --version

# View help
rtm --help
```

---

## Performance Optimization Tips

### Windows-Specific Optimizations

1. **Disable Windows Defender for development directory:**
   - Add project folder to exclusions in Windows Security
   - Significantly improves file I/O performance

2. **Use SSD for development:**
   - Store projects on SSD drive
   - Especially important for PostgreSQL data directory

3. **Increase WSL2 memory allocation:**

   Create/edit `%USERPROFILE%\.wslconfig`:

   ```ini
   [wsl2]
   memory=8GB
   processors=4
   swap=2GB
   ```

   Restart WSL: `wsl --shutdown`

4. **Use Windows Terminal:**
   - Better performance than Command Prompt
   - Supports multiple tabs and panes
   - Better Unicode and emoji support

---

## Next Steps

After setting up your development environment:

1. **Review Core Concepts**: [Core Concepts](/user/concepts)
2. **Create First Project**: [First Project Tutorial](/docs/getting-started/first-project)
3. **Explore IDE Setup**: [IDE Configuration](/docs/development/setup/ide-setup)
4. **Run Tests**: [Testing Guide](/docs/development/testing)
5. **Start Contributing**: [Contributing Guide](/docs/development/contributing)

---

## Additional Resources

### Windows Development Tools

- **Windows Terminal**: Modern terminal with tabs and themes
- **PowerToys**: Microsoft utilities for power users
- **WSLg**: GUI apps in WSL2
- **Docker Desktop**: Container runtime for Windows

### WSL2 Resources

- [WSL Documentation](https://docs.microsoft.com/en-us/windows/wsl/)
- [WSL Best Practices](https://docs.microsoft.com/en-us/windows/wsl/setup/environment)
- [VS Code WSL Tutorial](https://code.visualstudio.com/docs/remote/wsl)

### Troubleshooting Resources

- [WSL GitHub Issues](https://github.com/microsoft/WSL/issues)
- [PostgreSQL Windows Documentation](https://www.postgresql.org/docs/current/install-windows.html)
- [Python Windows FAQ](https://docs.python.org/3/faq/windows.html)

---

## Support

If you encounter issues not covered in this guide:

1. Check the [Troubleshooting Guide](/docs/development/troubleshooting)
2. Search existing [GitHub Issues](https://github.com/tracertm/tracertm/issues)
3. Join our [Discord Community](https://discord.gg/tracertm)
4. Create a new [GitHub Issue](https://github.com/tracertm/tracertm/issues/new) with:
   - Windows version
   - Setup method (WSL2 or Native)
   - Python version
   - Full error messages
   - Steps to reproduce
