Installation

Prerequisites

Before installing py-psscriptanalyzer, ensure you have the following prerequisites:

Python

py-psscriptanalyzer requires Python 3.9 or later.

python --version  # Should be 3.9 or higher

PowerShell

The package requires PowerShell Core (pwsh) to be installed and available in your system PATH.

Windows

Option 1: Microsoft Store (Recommended)

# Install from Microsoft Store using winget
winget install --id Microsoft.PowerShell --source winget

Option 2: Direct Download (Windows)

Download from the PowerShell GitHub releases page.

macOS

Option 1: Homebrew (Recommended)

brew install --cask powershell

Option 2: Direct Download (macOS)

Download from the PowerShell GitHub releases page.

Linux

Ubuntu/Debian

# Update package index
sudo apt update

# Install dependencies
sudo apt install -y wget apt-transport-https software-properties-common

# Download Microsoft signing key and repository
wget -q "https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb"
sudo dpkg -i packages-microsoft-prod.deb

# Update package index after adding Microsoft repository
sudo apt update

# Install PowerShell
sudo apt install -y powershell

CentOS/RHEL/Fedora

# Register Microsoft signature key
sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc

# Register Microsoft repository
curl https://packages.microsoft.com/config/rhel/8/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo

# Install PowerShell
sudo dnf install -y powershell

Verify PowerShell Installation

After installation, verify PowerShell is working:

pwsh --version

You should see output similar to:

PowerShell 7.5.2

Installing py-psscriptanalyzer

Method 1: PyPI (Recommended)

Install directly from PyPI using pip:

pip install py-psscriptanalyzer

Method 2: From Source

Install directly from the GitHub repository:

pip install git+https://github.com/thetestlabs/py-psscriptanalyzer.git

Verify Installation

After installation, verify the CLI is working:

py-psscriptanalyzer --help

Using as Pre-commit Hook

Method 1: Add to Existing .pre-commit-config.yaml

If you already have a .pre-commit-config.yaml file in your repository, add the py-psscriptanalyzer hooks:

repos:
  # ... your existing hooks ...

  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.1  # Use the latest version
    hooks:
      # Lint PowerShell files
      - id: py-psscriptanalyzer
        args: ["--severity", "Warning"]

      # Format PowerShell files
      - id: py-psscriptanalyzer-format

Method 2: Create New .pre-commit-config.yaml

Create a new .pre-commit-config.yaml file in your repository root:

repos:
  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.1  # Use the latest version
    hooks:
      - id: py-psscriptanalyzer
      - id: py-psscriptanalyzer-format

Install and Run Pre-commit

# Install pre-commit (if not already installed)
pip install pre-commit

# Install the git hook scripts
pre-commit install

# Run against all files (optional)
pre-commit run --all-files

Development Installation

For development or contributing to py-psscriptanalyzer:

# Clone the repository
git clone https://github.com/thetestlabs/py-psscriptanalyzer.git
cd py-psscriptanalyzer

# Install uv (if not already installed)
pip install uv

# Install dependencies
uv sync --group dev

# Install in editable mode
uv pip install -e .

Troubleshooting

PowerShell Not Found

If you get an error that PowerShell is not found:

Ensure PowerShell is installed (see prerequisites above)

Verify PowerShell is in your PATH:

which pwsh  # On Unix-like systems
where pwsh  # On Windows

Try running PowerShell directly:

pwsh -Command "Write-Output 'Hello World'"

PSScriptAnalyzer Module Missing

The first time you run py-psscriptanalyzer, it will automatically attempt to install the PSScriptAnalyzer PowerShell module. If this fails:

Install manually:

pwsh -Command "Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser"

Verify installation:

pwsh -Command "Get-Module -ListAvailable PSScriptAnalyzer"

Permission Issues

On Unix-like systems, you might need to update the PowerShell execution policy:

pwsh -Command "Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser"