PowerShell has a robust scripting environment that allows for quick and flexible code creation. But what happens when a script that relies on PowerShell 7 or specific modules gets executed on PowerShell 5.1? It fails, often with confusing errors. Enter the #requires statement—a feature that allows you to preemptively enforce prerequisites for your scripts.

If you remember, we actually talked about it earlier this month on how to use the #requires -RunAsAdministrator statement to make a script require being executed in an Admin PS session. But #requires can do a lot more!

The #requires statement ensures that your script will only execute under the proper conditions, such as the right PowerShell version, required modules, or user privileges. If these prerequisites aren’t met, PowerShell immediately throws an error and stops the script—saving you time and unnecessary troubleshooting.

Let’s dive into how to use the #requires statement effectively.

As we covered a couple weeks ago, the #requires statement must be placed at the very top of your script. It is processed before any other code executes. If the conditions defined in the #requires line aren’t met, the script bails and halts immediately.

Here’s a basic example that enforces a PowerShell version:

1
2
3

#requires -Version 7.0

# rest of script here

So if someone tries to run this script in PowerShell 5.1, they’ll see an immediate error like this:

The script is not supported on this system. PowerShell version 7.0 or greater is required.

Key Options for #requires

The #requires statement has several options that allow you to define exactly what your script needs. Here are the most common:

  1. -Version: Enforces a minimum PowerShell version.
  2. -Modules: Ensures required modules are available.
  3. -RunAsAdministrator: Requires the script to run with elevated privileges (covered a couple weeksback)
  4. -PSSnapin (legacy): Ensures a specific snap-in is available (mostly for older scripts).

Leaving out #Requires -RunAsAdministrator that we already covered, and the old legacy -PSSnapin, let’s look at the #requires -Modules option in more detail:

Requiring Modules

Sometimes your script depends on certain modules to function correctly. Instead of manually checking for their existence, use #requires to enforce them:

1
2
3

#requires -Modules ActiveDirectory, Az

# rest of script here

This line ensures the ActiveDirectory and Az modules are available. If they’re missing, PowerShell stops execution and throws an error.

Combining Multiple Requirements

You can combine multiple #requires statements to enforce complex conditions. For example:

1
2
3
4
5

#requires -Version 7.0
#requires -Modules ActiveDirectory
#requires -RunAsAdministrator

# rest of script here

So this script will only execute if:

  1. PowerShell 7.0 (or higher) is running.
  2. The ActiveDirectory module is available.
  3. The user has administrative privileges.

How #requires Improves Script Resilience

By using #requires, you avoid runtime errors caused by missing prerequisites. Instead of a cryptic failure halfway through the script, the user gets an immediate and clear error message—saving both time and frustration.

For example, instead of doing this manually:

1
2
3
4

if ($PSVersionTable.PSVersion.Major -lt 7) {
    Write-Error "This script requires PowerShell 7.0 or greater!"
    exit
}

You can simply write:

1

#requires -Version 7.0

It’s cleaner, more elegant, and follows best practices.

Best Practices for #requires

  1. Always Place #requires at the Top: It must be the very first executable line in your script.
  2. Be Specific: Use -Version and -Modules to communicate clear requirements.
  3. Combine Requirements: Use multiple #requires lines if your script has multiple dependencies.
  4. Document Prerequisites: Even with #requires, include comments explaining why certain conditions are needed.

Example Script

Here’s an example of a script that requires PowerShell 7, the Az module, and administrative privileges:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

#requires -Version 7.0
#requires -Modules Az
#requires -RunAsAdministrator

# Sample Script: Retrieve Azure Resource Groups
Write-Output "Checking Azure Resource Groups..."

# Connect to Azure
Connect-AzAccount

# List Resource Groups
Get-AzResourceGroup | Select-Object ResourceGroupName, Location

If someone runs this script without PowerShell 7, the Az module, or admin rights, they’ll get an immediate and clear error.

When Not to Use #requires

While #requires is extremely helpful, there are a few situations where it might not be appropriate:

  1. Ad-Hoc One-Liners: For quick testing or one-off scripts, enforcing prerequisites may be overkill.
  2. Non-Critical Scripts: For scripts that won’t cause harm if prerequisites are missing, manual checks may suffice.
  3. Legacy Environments: If you’re working in environments with older PowerShell versions, consider backward compatibility carefully.

Takeaways…

The #requires statement is a simple yet powerful way to enforce pre-reqs in your PowerShell scripts. By using it, you can ensure your code runs under the correct conditions, reducing errors and making your scripts more reliable.

Give #requires a spin in your next script, your future self will thank you! 🚀