Skip to content

Prerequisites

Ensure you have the required tools before setting up provide-workspace.

Required Tools

1. Python 3.11+

Python 3.11 or later is required for all ecosystem packages.

python3 --version  # Should be 3.11 or higher

Installation:

brew install [email protected]

sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev

sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev

2. uv (Modern Python Package Installer)

uv is a fast Python package installer and resolver written in Rust.

# Check if installed
uv --version

Installation:

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

After installation, restart your shell or source your profile:

source ~/.bashrc  # or ~/.zshrc

Learn more: uv documentation

3. Git

Version control for all ecosystem repositories.

git --version

Installation:

brew install git

sudo apt install git

sudo apt install git

Configuration:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

For working with GitHub repositories, issues, and PRs.

gh --version

Installation:

brew install gh

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

Same as Ubuntu/Debian

Authentication:

gh auth login

Follow prompts to authenticate with GitHub.

5. Make (For Documentation Builds)

Build automation tool used for documentation.

make --version

Installation:

# Usually pre-installed with Xcode Command Line Tools
xcode-select --install

sudo apt install build-essential

sudo apt install build-essential

6. Go 1.21+ (For Some Tooling Components)

Required for certain provider components and tooling.

go version

Installation:

brew install go

# Download from https://go.dev/dl/
wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

Same as Ubuntu/Debian

System Requirements

Operating System

  • macOS - 10.15 (Catalina) or later
  • Linux - Ubuntu 20.04+, Debian 11+, or equivalent
  • Windows - WSL2 with Ubuntu 20.04+ (Windows native is not supported)

Hardware

  • RAM: 8GB minimum, 16GB recommended
  • Disk Space: 5GB+ free space for repositories and virtual environments
  • CPU: Any modern multi-core processor (x86_64 or ARM64)

Verification Checklist

Before proceeding to installation, verify all tools are installed:

# Quick verification script
echo "Python: $(python3 --version)"
echo "uv: $(uv --version)"
echo "Git: $(git --version)"
echo "GitHub CLI: $(gh --version 2>/dev/null || echo 'not installed (optional)')"
echo "Make: $(make --version | head -n1)"
echo "Go: $(go version)"

All required tools should display version numbers. If any are missing, install them using the instructions above.

Next Steps

Once all prerequisites are installed, proceed to Installation for the setup process.

Troubleshooting

Python 3.11 Not Available

If your system package manager doesn't have Python 3.11+, consider using pyenv:

# Install pyenv
curl https://pyenv.run | bash

# Install Python 3.11
pyenv install 3.11.0
pyenv global 3.11.0

uv Installation Issues

If the uv installation script fails, try the alternative method:

pip install uv

Or download pre-built binaries from uv releases.

Permission Errors

If you encounter permission errors during installation, do not use sudo with uv or pip. Instead, use user installations:

uv venv  # Creates virtual environment
source .venv/bin/activate