📦 Installation Guide¶

This guide covers everything you need to install Pyvider and set up your development environment for building Terraform providers in Python.

🚦 System Requirements¶

Minimum Requirements¶

Python: 3.11 or higher
Operating System: Linux, macOS, or Windows
Memory: 2GB RAM minimum
Disk Space: 500MB for Pyvider and dependencies

Recommended Setup¶

Python: 3.11+ (latest stable version)
Package Manager: uv for fast dependency management
IDE: VS Code or PyCharm with Python extensions
Memory: 4GB+ RAM for comfortable development

🎯 Installation Methods¶

Method 1: Using pip (Simple)¶

The quickest way to get started with Pyvider:

# Basic installation
pip install pyvider

Note: Pyvider uses dependency groups (via uv) rather than extras. For development dependencies, see Method 2.

Method 2: Using uv (Recommended)¶

uv is a blazing-fast Python package manager that we recommend for Pyvider development:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a new project
uv init my-provider
cd my-provider

# Add Pyvider as a dependency
uv add pyvider

# For development, use sync to include dev dependencies
uv sync --group dev

Method 3: From Source (Development)¶

For contributing or testing the latest features:

# Clone the repository
git clone https://github.com/provide-io/pyvider.git
cd pyvider

# Set up development environment with uv
uv sync --group dev

# Install in editable mode
uv pip install -e .

# Run tests to verify installation
uv run pytest

🔧 Environment Setup¶

1. Virtual Environment (Recommended)¶

Always use a virtual environment to avoid dependency conflicts:

# Create virtual environment
python -m venv .venv

# Activate it
# On Linux/macOS:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# Install Pyvider
pip install pyvider

2. Development Environment Setup¶

For provider development, set up your project structure:

# Create project structure
mkdir -p my_provider/{provider,resources,data_sources,functions,tests}
touch my_provider/__init__.py
touch my_provider/provider/__init__.py
touch my_provider/resources/__init__.py
touch my_provider/data_sources/__init__.py
touch my_provider/functions/__init__.py

3. Environment Variables¶

Configure optional environment variables:

# Enable debug logging
export PYVIDER_LOG_LEVEL=DEBUG

# Set custom plugin directory
export PYVIDER_PLUGIN_DIR=~/.terraform.d/plugins

# Enable performance profiling
export PYVIDER_PROFILE=1

📋 Dependency Configuration¶

pyproject.toml Example¶

Here's a complete pyproject.toml for a Pyvider provider project:

[project]
name = "my-terraform-provider"
version = "0.1.0"
description = "A Terraform provider built with Pyvider"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "pyvider>=0.0.1000",
    "httpx>=0.24.0",  # For HTTP APIs
]

[dependency-groups]
dev = [
    "pytest>=7.0.0",
    "pytest-asyncio>=0.21.0",
    "pytest-cov>=4.0.0",
    "mypy>=1.0.0",
    "ruff>=0.1.0",
]

[build-system]
requires = ["setuptools>=65", "wheel"]
build-backend = "setuptools.build_meta"

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"
addopts = "-v --cov=my_provider --cov-report=term-missing"

[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
warn_unused_configs = true

[tool.ruff]
line-length = 100
target-version = "py311"
select = ["E", "F", "I", "N", "W", "B", "UP"]
ignore = ["E501"]  # Line too long

[tool.black]
line-length = 100
target-version = ["py311"]

✅ Verification¶

After installation, verify everything is working:

1. Check Pyvider Installation¶

# Verify Pyvider is installed
python -c "import pyvider; print(pyvider.__version__)"

# Check CLI availability and list available commands
pyvider --help

2. Run Component Discovery Test¶

Create a simple test file to verify component discovery:

# test_installation.py
from pyvider.providers import register_provider
from pyvider.resources import register_resource

@register_provider("test")
class TestProvider:
    """Test provider to verify installation"""
    metadata = {"name": "test", "version": "0.1.0"}

@register_resource("test_resource")
class TestResource:
    """Test resource"""
    pass

if __name__ == "__main__":
    from pyvider.hub import ComponentHub
    hub = ComponentHub()
    print(f"Found {len(hub.providers)} provider(s)")
    print(f"Found {len(hub.resources)} resource(s)")

Run it:

python test_installation.py
# Should output:
# Found 1 provider(s)
# Found 1 resource(s)

3. Test CLI Commands¶

# List discovered components
pyvider components list

# Show effective configuration
pyvider config show

# Inspect launch context / environment
pyvider launch-context

🔌 IDE Setup¶

Visual Studio Code¶

Install recommended extensions:

// .vscode/extensions.json
{
    "recommendations": [
        "ms-python.python",
        "ms-python.vscode-pylance",
        "charliermarsh.ruff",
        "ms-python.mypy-type-checker",
        "littlefoxteam.vscode-python-test-adapter"
    ]
}

Configure settings:

// .vscode/settings.json
{
    "python.linting.enabled": true,
    "python.linting.ruffEnabled": true,
    "python.formatting.provider": "black",
    "python.testing.pytestEnabled": true,
    "python.testing.unittestEnabled": false,
    "[python]": {
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.organizeImports": true
        }
    }
}

PyCharm¶

Open Settings → Project → Python Interpreter
Add Pyvider to your project interpreter
Enable pytest as the test runner
Configure mypy for type checking
Set up ruff for linting

🐳 Docker Setup (Optional)¶

For containerized development:

# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Pyvider
RUN pip install --no-cache-dir pyvider

# Copy your provider code
COPY . .

# Install provider dependencies
RUN pip install --no-cache-dir -e .

# Run provider
CMD ["pyvider", "provide"]

Build and run:

docker build -t my-provider .
docker run -p 50051:50051 my-provider

🚨 Common Installation Issues¶

Issue: Python Version Too Old¶

ERROR: pyvider requires Python 3.11 or higher

Solution: Upgrade Python or use pyenv to manage versions:

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

# Install Python 3.11
pyenv install 3.11.7
pyenv global 3.11.7

Issue: Missing Build Tools¶

ERROR: Microsoft Visual C++ 14.0 is required (Windows)
ERROR: error: Microsoft Visual C++ 14.0 or greater is required

Solution: Install build tools: - Windows: Install Visual Studio Build Tools - macOS: Install Xcode Command Line Tools: xcode-select --install - Linux: Install build-essential: sudo apt-get install build-essential

Issue: Permission Denied¶

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

Solution: Use a virtual environment or install with --user:

pip install --user pyvider

Issue: Conflicting Dependencies¶

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed

Solution: Use uv or create a fresh virtual environment:

# With uv
uv venv
uv pip install pyvider

# With standard venv
python -m venv fresh_env
source fresh_env/bin/activate
pip install pyvider

🔄 Upgrading Pyvider¶

Keep Pyvider up to date for the latest features and fixes:

# Using pip
pip install --upgrade pyvider

# Using uv
uv sync --upgrade

# Check current version
python -c "import pyvider; print(pyvider.__version__)"

Note: Pyvider is in alpha. Breaking changes may occur between releases. Check the release notes before upgrading.

📚 Next Steps¶

Now that you have Pyvider installed:

Quick Start Guide - Build your first provider in 5 minutes
Pyvider Components Examples - 100+ working examples
Architecture Overview - Understand how Pyvider works
API Reference - Explore the API documentation

💬 Getting Help¶

If you encounter issues during installation:

Ready to build? Continue to the Quick Start Guide →