When writing PowerShell scripts, you often need to pause execution for a specific time—maybe waiting for a process to finish or adding a delay between commands. The Start-Sleep cmdlet is the built-in tool for this. In this guide, you’ll learn exactly how to use it, avoid common pitfalls, and apply practical examples.

What Is Start-Sleep and Why Use It?

Start-Sleep suspends the activity in a script or session for a specified period. It’s useful for:

  • Waiting for a service to start or stop.
  • Adding a pause between retries in a loop.
  • Simulating user interaction delays.
  • Throttling API calls to avoid rate limits.

Unlike a simple loop that wastes CPU cycles, Start-Sleep is efficient and accurate.

Syntax and Parameters

The basic syntax is:

Start-Sleep [-Seconds] <int> [-Milliseconds] <int> [<CommonParameters>]

Two key parameters:

  • -Seconds: Number of seconds to sleep (default). Can be a whole number or decimal (e.g., 1.5).
  • -Milliseconds: Number of milliseconds to sleep. Use for finer control.

You cannot use both at the same time. Choose one.

Practical Examples

Example 1: Pause for 5 seconds

Start-Sleep -Seconds 5

Example 2: Pause for 500 milliseconds

Start-Sleep -Milliseconds 500

Example 3: Using a variable

$delay = 10
Start-Sleep -Seconds $delay

Example 4: In a loop with retry logic

$retryCount = 0
do {
try {
Invoke-WebRequest -Uri 'https://api.example.com' -ErrorAction Stop
break
} catch {
$retryCount++
if ($retryCount -ge 3) { throw }
Write-Host 'Retrying in 2 seconds...'
Start-Sleep -Seconds 2
}
} while ($true)

Common Mistakes and How to Avoid Them

  • Using both -Seconds and -Milliseconds: This causes an error. Pick one.
  • Assuming Start-Sleep works across threads: It only pauses the current session or script, not other processes.
  • Overusing long delays: Blocking the script for too long can make it unresponsive. Use shorter delays in loops.
  • Forgetting that -Seconds accepts decimals: You can use 0.5 for half a second, but it’s more readable to use -Milliseconds 500.

Real-World Usage Tips

  • Throttling API calls: Many APIs limit requests per second. Add a Start-Sleep after each call to stay within limits.
  • Waiting for file operations: After copying a file, use Start-Sleep before checking its existence to avoid race conditions.
  • Simulating user input: When automating UI tasks, small delays (e.g., 200 ms) make interactions more reliable.

FAQ

Can I stop a Start-Sleep early?
Yes, press Ctrl+C to break out of the sleep.

Does Start-Sleep use CPU?
No, it suspends the thread, so CPU usage is minimal.

What’s the maximum sleep time?
Technically, it’s limited by the integer range (about 24 days for seconds).

Can I use Start-Sleep in a background job?
Yes, but it will only sleep that job’s runspace, not the main session.

Conclusion

Start-Sleep is a simple but powerful cmdlet for adding delays in PowerShell. By understanding its parameters and avoiding common mistakes, you can write scripts that wait precisely when needed. Practice with the examples above, and you’ll master it in no time.

start-sleep
Recommended

Related Articles