> For the complete documentation index, see [llms.txt](https://www.osdeploy.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.osdeploy.com/osdeploy-insider/how-to/osdeploy-boot-customize-winpe-with-powershell-script.md).

# OSDeploy Boot: Customize WinPE with a PowerShell Script

Add a custom PowerShell script that runs while Build-OSDeployBoot services the mounted WinPE image.

Place a PowerShell script in the shared `boot-winpescript` library when it must customize the mounted WinPE image during `Build-OSDeployBoot`.

{% hint style="info" %}
A WinPE build script runs on the OSDeploy workstation in the current PowerShell session. It does not become a startup script unless the script explicitly copies content into the mounted image.
{% endhint %}

## Create the Script

Create the shared script directory and a script that writes a marker file into WinPE:

```powershell
$ScriptDirectory = Join-Path $env:ProgramData 'OSDeployCore\boot-assets\boot-winpescript'
$ScriptPath = Join-Path $ScriptDirectory 'Add-ContosoMarker.ps1'

New-Item -Path $ScriptDirectory -ItemType Directory -Force | Out-Null

@'
$MountPath = $global:BuildMedia.MountPath

if (-not $MountPath -or -not (Test-Path -LiteralPath $MountPath -PathType Container)) {
    throw "The OSDeploy WinPE mount path is not available."
}

$Destination = Join-Path $MountPath 'Windows\System32\Contoso'
New-Item -Path $Destination -ItemType Directory -Force | Out-Null
Set-Content -LiteralPath (Join-Path $Destination 'Build.txt') `
    -Value "Built $([datetime]::Now.ToString('s'))" `
    -Encoding utf8
'@ | Set-Content -LiteralPath $ScriptPath -Encoding utf8
```

Use `$global:BuildMedia.MountPath` for files that belong inside WinPE. Throw when required input or an operation fails so the build log identifies the problem.

## Select the Script

Start an interactive build and select `Add-ContosoMarker.ps1` when the WinPE script picker appears:

```powershell
Build-OSDeployBoot
```

## Build and Verify

Complete the remaining prompts to build the media. The script runs near the end of mounted-image servicing, before WinpeStartup content and drivers are added. Script success-stream output is passed through by the build step; a script failure writes a non-terminating error and later build steps can continue.

Boot the resulting media and confirm this file exists:

```
X:\Windows\System32\Contoso\Build.txt
```

Use `boot-mediascript` instead when a script must modify the completed media after the WIM is dismounted. See [OSDeployCore Boot-Assets](/osdeploy-insider/reference/osdeploycore-boot-assets.md) for the two script lifecycles.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.osdeploy.com/osdeploy-insider/how-to/osdeploy-boot-customize-winpe-with-powershell-script.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.