What are Your PowerShell Newbie Gotchas?

I'm putting together a list of common "gotchas" for PowerShell, mainly things that affect newcomers. So far, I've got:

  • Piping the output of a Format cmdlet to nearly anything else
  • Using -contains instead of -like
  • Selecting a subset of object properties and then trying to sort/fiter on a now-missing property
  • Wrong syntax for -filter parameters on various commands
  • Commands that don't produce pipeline output (e.g., piping Export-CSV to something)
  • Using ConvertTo-HTML without -Fragment and appending multiple pages in one file
  • Confusion with ( [ { and the other punctuation
  • Concatenating strings (hard) vs. using double quotes (easier)
  • $ not being part of the variable name (esp with -ErrorVariable)
  • Accumulating objects in a variable and returning it, vs. outputting to the pipeline directly

What are your "gotchas?"

About the Author

Don Jones

Don Jones is a Windows PowerShell MVP, author of several Windows PowerShell books (and other IT books), Co-founder and President/CEO of PowerShell.org, PowerShell columnist for Microsoft TechNet Magazine, PowerShell educator, and designer/author of several Windows PowerShell courses (including Microsoft’s). Power to the shell!


  1. Another cause of problems I see fairly often is mistakes that arise from confusion about the difference between foreach and foreach-object (like using $_ in a foreach loop).

  2. The verbal smack down because you are not that familiar with "how to find" all the information in the Help File... I am asking for guidance and an explanation so that I can understand better and help those I work with do the same. If I did not "think" you knew the answer, I would not have asked for your assistance.... If you are that busy to waste your time answering with helpful information then please don't reply. The effort put forth to smack someone down for what you perceive as "D'Uh! this is obvious", could have been used to enlighten instead.

      • A "gotcha" in that newbies (and myself as well) have this fear that they "should" know these things and are scared to death to be made to feel like an idiot. So they will literally give up... If you are not comfortable enough to ask a basic question, then your learning skills with be greatly hampered. Not you or Jeff or Ed or Mark or Jeremy of course. If not for you guys, Powershell would not be as popular and supported as it is today.

  3. Some of the common aliases are in fact aliases and NOT actual commands. For example, 'ls' works, but 'ls -l' does not. 'Dir' works, but 'Dir /w' does not.

    When getting started, might want to consider adding start-transcript to your profile along with code to manage those archives. That will also flush out the execution policy issue. Archiving the transcript has helped me in cases where I had the command working the way I wanted at the end of the day yesterday, but don't remember what I had done. 😉

    Remember that tab completion is your friend! Not a gotcha, but definitely something to remember.

    I still get burned by two-hop authentication on a regular basis.

    I'm still a newbie after several years. Learning PowerShell takes dedicated practice time!

  4. A few I'd like to mention
    * Calling cmdlets and functions as if they were methods (i.e. using parens and commas)
    * Using "\r" or "\n" instead of "`r" and "`n"
    * Accidentally returning more than intended in a function (inadvertent expressions in the output)
    * Cmdlets returning one object instead of a collection (and trying to foreach through them)

  5. I have just been writing a script and one of the issues is being able to wrap long lines of code so it appears in the PSE window. I know about being able to use the pipeline as a "soft return" however the other day I discovered ` (think this is back tick) it does do something similar but I am not completely certain where to use it exactly. (the script works, but I would like to understand this better)

    Oh and how to create loops - sorry, my background is not programming.

    • The backtick is an escape character. When it comes IMMEDIATELY before a carriage return, it escapes it, making it a "soft" line break rather than a logical end-of-line. It's kinda frowned on by a lot of people because it's so bloody hard to see. In a book, it looks like a speck of stray toner. You can also legally hit Enter after a semicolon or comma, so it's not *too* often you need more line breaking than that. On a long command with a lot of params, you use splatting - put the params in a hashtable and splat it, so you can code one param per line.

      • Thanks for the explanation. That helps, yes I agree it a real pain to spot, I did think it was a speck of dust on the screen at one point. Think I understand the parameters in a hash table, will go and look at the code again and see if I can lose the back tick!