PSDepend

PSDepend is a PowerShell dependency handler. Define your dependencies in a simple .psd1 file and let Invoke-PSDepend install them — similar to pip install -r requirements.txt or bundle install.

Installing

# PowerShell 7+ (recommended)
Install-PSResource PSDepend

# PowerShell 5.1
Install-Module PSDepend

# Manual
# Download and unblock the repository zip, then extract the PSDepend folder
# to a module path (e.g. $env:USERPROFILE\Documents\WindowsPowerShell\Modules\)

Quick Start

Import-Module PSDepend
Get-Command -Module PSDepend
Get-Help about_PSDepend

Defining Dependencies

Store dependencies in a PowerShell data file named *.depend.psd1 or requirements.psd1. Invoke-PSDepend will find these files automatically.

Simple syntax

@{
    psake        = 'latest'
    Pester       = 'latest'
    BuildHelpers = '0.0.20'
    PSDeploy     = '0.1.21'

    'PowerShellOrg/PSDepend' = 'main'
}

PSDepend infers PSGalleryModule for bare names and GitHub for owner/repo entries:

DependencyName          DependencyType  Version Tags
--------------          --------------  ------- ----
psake                   PSGalleryModule latest
BuildHelpers            PSGalleryModule 0.0.20
Pester                  PSGalleryModule latest
PowerShellOrg/PSDepend  GitHub          main
PSDeploy                PSGalleryModule 0.1.21

You can also specify the dependency type explicitly:

@{
    'PSGalleryModule::InvokeBuild'       = 'latest'
    'GitHub::PowerShellOrg/PSDepend'     = 'main'
}

Flexible syntax

For more control, use the hashtable syntax. You can mix and match styles within the same file:

@{
    psdeploy = 'latest'

    buildhelpers_0_0_20 = @{
        Name = 'buildhelpers'
        DependencyType = 'PSGalleryModule'
        Parameters = @{
            Repository = 'PSGallery'
            SkipPublisherCheck = $true
        }
        Version = '0.0.20'
        Tags = 'prod', 'test'
        PreScripts = 'C:\RunThisFirst.ps1'
        DependsOn = 'some_task'
    }

    some_task = @{
        DependencyType = 'task'
        Target = 'C:\RunThisFirst.ps1'
        DependsOn = 'nuget'
    }

    nuget = @{
        DependencyType = 'FileDownload'
        Source = 'https://dist.nuget.org/win-x86-commandline/latest/nuget.exe'
        Target = 'C:\nuget.exe'
    }
}

To inspect the full dependency output:

$Dependency = Get-Dependency \\Path\To\complex.depend.psd1
$Dependency[2] | Select-Object *

DependencyFile : \\Path\To\complex.depend.psd1
DependencyName : buildhelpers_0_0_20
DependencyType : PSGalleryModule
Name           : buildhelpers
Version        : 0.0.20
Parameters     : {Repository,SkipPublisherCheck}
Source         :
Target         :
AddToPath      :
Tags           : {prod, test}
DependsOn      : some_task
PreScripts     : C:\RunThisFirst.ps1
PostScripts    :
Raw            : {Version, Name, Tags, DependsOn...}

The following strings are expanded in Target and Source fields: $PWD (or .), $ENV:USERPROFILE, $ENV:TEMP, $ENV:ProgramData, $ENV:APPDATA. Use single quotes or escape the $ to prevent PowerShell from expanding them before PSDepend can: Target = '$PWD\dependencies'.

Repository Credentials

For private repositories that require authentication, set a Credential key in the dependency and pass a matching PSCredential object to Invoke-PSDepend:

@{
    buildhelpers_0_0_20 = @{
        Name = 'buildhelpers'
        DependencyType = 'PSGalleryModule'
        Parameters = @{
            Repository = 'MyPrivateGallery'
        }
        Version = '0.0.20'
        Credential = 'my_gallery'
    }
}

Invoke-PSDepend -Path C:\requirements.psd1 -Credentials @{ 'my_gallery' = $creds }

The credential key must match between the dependency definition and the hashtable passed to -Credentials.

Locking Dependencies

Like npm's package-lock.json, PSDepend can pin every dependency — and the dependencies they pull in — to exact versions so that every machine installs the same thing:

Update-PSDependLock -Path .\requirements.psd1   # writes requirements.lock.json
Invoke-PSDepend -Path .\requirements.psd1       # installs the locked versions

Update-PSDependLock asks each dependency type that supports the Resolve action (PSGalleryModule, PSResourceGet, PSGalleryNuget, Nuget, Chocolatey, Npm) for the highest version that satisfies the declared Version and walks that package's own dependencies. The gallery, NuGet, and Chocolatey types accept NuGet ranges; Npm accepts npm semver ranges such as ^1.2.0 or >=1 <2 and rejects NuGet range syntax. Npm pins only the declared package because npm's own package-lock.json governs its subtree.

One version is locked per DependencyType::Name. Resolution is greedy: after selecting a parent version, PSDepend intersects child constraints but does not backtrack to an older parent version. Narrow the parent's range if an older version is required. Packages reached from roots with different installation contexts are installed once per root.

Once a lock exists next to a dependency file, Invoke-PSDepend and Get-Dependency use it automatically. Locked transitive packages install first. A changed dependency, version, resolution source, or DependencyScript parameter makes the lock out of date; removing every dependency does too. Pass -IgnoreLock to use the DependencyFile without the lock. With Invoke-PSDepend -Test, locked root and transitive versions are tested.

Commit the .lock.json alongside the DependencyFile and review lock changes like code. PSDepend validates its structure and exact versions before use, but version 1 does not contain package content hashes.

The JSON contains lockfileVersion, dependencies, and packages. Root entries record the requested version, DependencyType::Name package key, and a hash of resolution Source/Parameters. Package entries record an exact version and direct dependency ranges. Synthesized transitive Dependency names normally use Name@Version; a #RootName suffix disambiguates a package installed for another root context.

Dependency types without a Resolve action (Git, GitHub, FileDownload, ...) are recorded in the lock for drift detection but install exactly as declared.

Getting Help

Each dependency type may handle standard properties differently and expose its own parameters. Use Get-PSDependType to see what is available:

Get-PSDependType

DependencyType  Description                                                 DependencyScript
--------------  -----------                                                 ----------------
PSGalleryModule Install a PowerShell module from the PowerShell Gallery.    C:\...\PSDepend\PSDepen...
Task            Support dependencies by handling simple tasks.              C:\...\PSDepend\PSDepen...
Noop            Display parameters that a depends script would receive...   C:\...\PSDepend\PSDepen...
FileDownload    Download a file                                             C:\...\PSDepend\PSDepen...

Read the comment-based help for any dependency type:

Get-PSDependType -DependencyType PSGalleryModule -ShowHelp

Additional help topics:

Get-Help about_PSDepend
Get-Help about_PSDepend_Definitions
Get-Help Get-Dependency -Full

Extending PSDepend

PSDepend is extensible. To add a new dependency type, create a script in the PSDependScripts folder and register it in PSDependMap.psd1.

Your script must:

• Include comment-based help describing how it uses Dependency metadata
• Accept Install, Test, and Import in PSDependAction; optionally accept Resolve as a fourth action
• For Resolve, query only and emit one PSDepend.ResolvedDependency with an exact Version and direct Dependencies; do not install

See Git.ps1 and PSGalleryModule.ps1 for reference implementations.

Examples

• Creating a virtual environment
• Handling module dependencies
• How Do I...

Contributing

Contributions are welcome. Please read the PowerShellOrg contributing guide before opening a pull request.

Acknowledgements

PSDepend was originally created by Warren Frame (RamblingCookieMonster) and is now maintained by the PowerShellOrg organization.

The concept was inspired by Michael Willis's PSRequire.