Set Up a Development Environment

This guide walks you through setting up a complete development environment for Babylon. It covers Linux, macOS, and Windows (via WSL).

Prerequisites Overview

Tool

Version

Purpose

Python

3.12 or higher

Runtime environment

Poetry

Any recent

Dependency management

Git

Any recent

Version control

(Windows) WSL 2

Ubuntu 22.04+

Linux environment on Windows

Linux / macOS Setup

Step 1: Install Python 3.12+

Ubuntu/Debian:

sudo apt update
sudo apt install python3 python3-pip python3-venv

macOS (with Homebrew):

brew install python@3.12

Verify installation:

python3 --version
# Should show: Python 3.12.x or higher

Step 2: Install Poetry

Poetry manages Python dependencies and virtual environments.

curl -sSL https://install.python-poetry.org | python3 -

Add Poetry to your PATH by adding this to your ~/.bashrc or ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

Reload your shell and verify:

source ~/.bashrc  # or ~/.zshrc
poetry --version

Step 3: Install Git

Ubuntu/Debian:

sudo apt install git

macOS:

# Git comes with Xcode Command Line Tools
xcode-select --install

Verify:

git --version

Step 4: Clone and Set Up the Project

# Clone the repository
git clone https://github.com/percy-raskova/babylon.git
cd babylon

# Install dependencies (creates virtual environment automatically)
poetry install

# Install pre-commit hooks
poetry run pre-commit install --hook-type commit-msg --hook-type pre-commit

# Verify everything works
poetry run pytest -m "not ai" -x -q

You should see all tests passing. You’re ready to develop!

Windows Setup (WSL + VSCode)

Windows users should use Windows Subsystem for Linux (WSL) for the best development experience. This gives you a full Linux environment that integrates seamlessly with VSCode.

Step 1: Install WSL 2

Requirements:

  • Windows 10 version 2004+ (Build 19041+) or Windows 11

  • Virtualization enabled in BIOS

Install WSL:

Open PowerShell as Administrator and run:

wsl --install

This command:

  • Enables the WSL feature

  • Installs the default Ubuntu distribution

  • Sets WSL 2 as the default version

Restart your computer when prompted.

Complete Ubuntu setup:

After restart, Ubuntu will launch automatically. Create your Linux username and password when prompted:

Enter new UNIX username: yourname
New password: ********
Retype new password: ********

Tip

This is a separate user account from Windows. Choose something memorable.

Verify WSL is working:

# In the Ubuntu terminal
cat /etc/os-release
# Should show Ubuntu version info

Step 2: Install VSCode with WSL Extension

Install VSCode on Windows:

Download from https://code.visualstudio.com/ and install normally.

Install the WSL extension:

  1. Open VSCode

  2. Press Ctrl+Shift+X to open Extensions

  3. Search for “WSL”

  4. Install WSL by Microsoft (extension ID: ms-vscode-remote.remote-wsl)

Note

The extension is called “WSL” (formerly “Remote - WSL”). It allows VSCode running on Windows to edit files inside WSL.

Step 3: Set Up Development Tools in WSL

Open your Ubuntu terminal (search for “Ubuntu” in Windows Start menu):

Update packages and install essentials:

sudo apt update && sudo apt upgrade -y
sudo apt install python3 python3-pip python3-venv git curl wget ca-certificates -y

Install Poetry:

curl -sSL https://install.python-poetry.org | python3 -

Add Poetry to PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify installations:

python3 --version   # Should be 3.12+
poetry --version    # Should show Poetry version
git --version       # Should show Git version

Step 4: Clone the Project in WSL

Important: Clone the project inside WSL’s filesystem, not on the Windows side. This ensures proper file permissions and much better performance.

# Create a projects directory in your WSL home
mkdir -p ~/projects
cd ~/projects

# Clone the repository
git clone https://github.com/percy-raskova/babylon.git
cd babylon

# Install dependencies
poetry install

# Install pre-commit hooks
poetry run pre-commit install --hook-type commit-msg --hook-type pre-commit

# Verify
poetry run pytest -m "not ai" -x -q

Step 5: Open Project in VSCode (Remote)

There are two ways to open your WSL project in VSCode:

Method A: From the WSL terminal (recommended):

# Navigate to the project
cd ~/projects/babylon

# Open in VSCode
code .

VSCode will launch on Windows but connect to WSL. You’ll see WSL: Ubuntu in the bottom-left corner of the VSCode window.

Method B: From VSCode on Windows:

  1. Open VSCode

  2. Press Ctrl+Shift+P to open Command Palette

  3. Type “WSL: Connect to WSL”

  4. Once connected, use File > Open Folder

  5. Navigate to /home/yourname/projects/babylon

Install recommended extensions in WSL:

When VSCode connects to WSL, you may need to reinstall some extensions “in WSL”. VSCode will prompt you for this. Recommended extensions:

  • Python (Microsoft)

  • Pylance

  • Ruff

  • GitLens

Step 6: Configure Git in WSL

Set up your Git identity:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Optional: Use Windows Git Credential Manager:

To share credentials between Windows and WSL:

git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

Using Mise (Optional)

The project uses mise as a task runner for common operations. While optional, it provides convenient shortcuts.

Install mise:

curl https://mise.run | sh
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
source ~/.bashrc

Common mise commands:

mise run test        # Run all non-AI tests
mise run test-fast   # Run fast math/engine tests
mise run lint        # Run Ruff linter
mise run typecheck   # Run MyPy
mise run ci          # Run all CI checks locally
mise run docs-live   # Start live documentation server
mise run security    # Run security audit on dependencies
mise run coverage    # Run tests with coverage report

Verifying Your Setup

Run through this checklist to confirm everything is working:

# 1. Python version
python3 --version
# Expected: Python 3.12.x or higher

# 2. Poetry works
poetry --version

# 3. Dependencies installed
poetry run python -c "import babylon; print('Babylon imported!')"

# 4. Tests pass
poetry run pytest -m "not ai" -x -q
# Expected: All tests pass

# 5. Pre-commit hooks installed
poetry run pre-commit run --all-files
# Expected: All hooks pass (may auto-fix some files)

# 6. Documentation builds
cd docs && poetry run sphinx-build -b html . _build/html
# Expected: No errors

Troubleshooting

Poetry command not found:

Ensure Poetry is in your PATH:

export PATH="$HOME/.local/bin:$PATH"
# Add to ~/.bashrc to make permanent

Tests fail with import errors:

Make sure you ran poetry install:

poetry install

WSL: “code” command not found:

Add VSCode to your WSL PATH in ~/.bashrc:

export PATH="$PATH:/mnt/c/Users/YOURWINDOWSUSER/AppData/Local/Programs/Microsoft VS Code/bin"

Replace YOURWINDOWSUSER with your Windows username.

WSL: Very slow file operations:

Make sure your project is in the WSL filesystem (~/projects/), not on the Windows filesystem (/mnt/c/...). WSL 2 has significant performance penalties when accessing Windows files.

Pre-commit hooks fail:

Run the fix commands:

poetry run ruff check . --fix
poetry run ruff format .

Then try committing again.

See Also