Posey's Tips & Tricks

How To Convert a PowerShell Script into an EXE File

Conversion makes sharing scripts much easier to do.

PowerShell scripts are great because they can be used to do almost anything. One of the limitations to PowerShell scripts, however, is that it isn't always practical to give a script to someone who does not work in IT. The average person probably isn't going to know that you have to type dot slash in front of the filename in order to execute the script, never mind the fact that they will have to configure their computer's execution policy to allow the script to run. But what if you could compile the script into an executable file? That might make script sharing more practical.

I have often pondered the idea of compiling some of my more elaborate PowerShell scripts into executable files for various reasons, but never really wanted to tackle the project due to its perceived difficulty. Recently, however, I was surprised to learn that Microsoft provides a free utility that can convert a PowerShell script into an executable file.

You can download the conversion utility, which is called PS2EXE, directly from TechNet here.

So before I show you how to build an EXE from your PowerShell scripts, I need to clarify that this tool does not perform a true conversion. Your scripts still run as native PowerShell, but are encapsulated into an EXE file. To quote the Microsoft Web page referenced above,  the utility "does not convert the PowerShell script to an other [sic] language! It encapsulates the script with a lightweight PowerShell host written in C# and compiles the dynamically generated C# source code in memory to an EXE file. The resulting EXE is an .NET assembly that contains the source script encoded in Base64. The EXE includes all stuff that is needed to execute an PowerShell through the .NET object model."

To use the PS2EXE tool, download it and extract the zip file contents into a folder on your hard disk. After doing so, converting a PowerShell script to EXE format is simply a matter of running PS2EXE (which is, itself, a PowerShell script), specifying the script that you want to convert and designate a filename for the resulting EXE file.

To show you how this works, I have downloaded PS2EXE and extracted its contents to a folder named Scripts on a Windows Server 2012 R2 machine.  This folder contains several preexisting PowerShell scripts, but for the sake of demonstration, I am going to convert a really simple PowerShell script named HelloWorld.ps1. So with that said, here is the syntax for the PS2EXE tool:

PS2EXE.ps1 -InputFile <path and filename of the PS1 script to be converted> -OutputFile <path and filename of the resulting EXE file>

Given this syntax, the command that I will be using to convert my HelloWorld.ps1 file is:

./PS2EXE.ps1 -InputFile C:\Scripts\HelloWorld.ps1 -OutputFile C:\Scripts\HelloWorld.exe

You can see the actual command and the resulting file in Figure 1.

[Click on image for larger view.] Figure 1. I have converted a PowerShell script into .EXE format.

Figure 2 confirms that I was able to run the newly created executable file.

[Click on image for larger view.] Figure 2. I was able to run my HelloWorld.exe file.

As you can see, converting a PowerShell script into an EXE file is a simple process. Even so, there are a couple of things that you need to know before you try this out on your own.

First, you won't be able to run the EXE file in PowerShell. Instead, you will need to open a Windows Command Prompt window, and run the EXE file there. You should also be able to run the file from the Windows Run prompt. If you do try to run the executable from within a PowerShell window, you will get an error similar to what you see in Figure 3.

[Click on image for larger view.] Figure 3. You cannot run an executable program inside of PowerShell.

A second thing to know is that the PS2EXE program is PowerShell version dependent. For right now, the utility is verified to work with PowerShell 4.0 (and some earlier versions). This means that you can run it on Windows Server 2012 R2, but it is not certified to work with Windows Server 2016 or Windows 10. Out of curiosity, I tried running the tool on a Windows 10 desktop and received a PowerShell version error.

One more thing that you need to know is that the PS2EXE tool has a dependency on the .NET Framework. Version 2.0 of the framework will need to be installed in order for the tool to work.

So with that said, have fun converting your PowerShell scripts. While you are at it, be sure to take the time to read the download page. There are some extra parameters that you can use to customize the tool's behavior. For example, it is possible to create 32-bit or 64-bit executables.

About the Author

Brien Posey is a 22-time Microsoft MVP with decades of IT experience. As a freelance writer, Posey has written thousands of articles and contributed to several dozen books on a wide variety of IT topics. Prior to going freelance, Posey was a CIO for a national chain of hospitals and health care facilities. He has also served as a network administrator for some of the country's largest insurance companies and for the Department of Defense at Fort Knox. In addition to his continued work in IT, Posey has spent the last several years actively training as a commercial scientist-astronaut candidate in preparation to fly on a mission to study polar mesospheric clouds from space. You can follow his spaceflight training on his Web site.


comments powered by Disqus

Subscribe on YouTube