Skip to main content

Installation Guide

System Requirements​

Minimum Requirements​

  • Python: 3.8 or higher
  • Operating System: Windows 10+, macOS 10.15+, Linux (modern distributions)
  • Memory: 2GB RAM minimum, 4GB recommended for large scans
  • Network: Internet connection for cloud API access

Optional Requirements​

  • Terraform: For validation and import operations
  • Cloud CLIs: AWS CLI, Azure CLI, or gcloud for authentication

Installation Methods​

The simplest way to install Terraback:

# Install from PyPI
pip install terraback

# Verify installation
terraback scan auth-check

pip with Virtual Environment​

For isolated installation:

# Create virtual environment
python -m venv terraback-env

# Activate virtual environment
# On Windows:
terraback-env\Scripts\activate
# On macOS/Linux:
source terraback-env/bin/activate

# Install Terraback
pip install terraback

# Verify
terraback scan auth-check

Standalone Binaries​

Download pre-built binaries for your platform — no Python required:

Linux:

curl -L -o terraback https://download.terraback.io/releases/latest/terraback-linux
chmod +x terraback
sudo mv terraback /usr/local/bin/
terraback --help

macOS:

curl -L -o terraback https://download.terraback.io/releases/latest/terraback-macos
chmod +x terraback
sudo mv terraback /usr/local/bin/
terraback --help

Windows:

Download terraback-windows.exe and add it to your PATH.

# Or via PowerShell
Invoke-WebRequest -Uri "https://download.terraback.io/releases/latest/terraback-windows.exe" -OutFile "terraback.exe"
.\terraback.exe --version

Cloud Provider Setup​

AWS​

Terraback uses standard AWS credential chain:

# Option 1: AWS CLI configuration
aws configure

# Option 2: Environment variables
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_DEFAULT_REGION="us-east-1"

# Option 3: AWS profile
aws configure --profile myprofile
terraback scan all aws --profile myprofile -r us-east-1 -o ./output

Required Permissions: ReadOnlyAccess policy or equivalent read permissions for services you want to scan.

Azure​

# Option 1: Azure CLI login
az login

# Option 2: Service principal
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"
export AZURE_TENANT_ID="your-tenant-id"
export AZURE_SUBSCRIPTION_ID="your-subscription-id"

Required Permissions: Reader role on the subscription or resource group.

GCP​

# Option 1: gcloud authentication
gcloud auth application-default login

# Option 2: Service account
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

Required Permissions: Viewer role on the project.

Verifying Installation​

Check Authentication​

# Check all providers
terraback scan auth-check

Test Scan​

# Quick test with S3 (usually has resources)
terraback aws s3 scan --region us-east-1 --output-dir ./test-output

Upgrading​

# Upgrade to latest version
pip install --upgrade terraback

Uninstalling​

pip uninstall terraback

Troubleshooting Installation​

Python Version Error​

Error: Python 3.8 or higher required

Solution: Install Python 3.8+ from python.org or use pyenv.

Permission Error (Linux/macOS)​

Error: Permission denied

Solution: Use a virtual environment or pip install --user terraback.

AWS Credentials Not Found​

Error: Unable to locate credentials

Solution: Run aws configure or set environment variables.

Next Steps​