Steamworks Documentation
Creating and using InstallScripts

Overview

While Steam can automatically install many common redistributables, your application may have other first-run requirements.
NOTE: Install script functionality described below is primarily for Windows operating systems. MacOS support is limited to file permissions and symlinks. There is no Linux/SteamOS install script functionality at this time.

An install script file is a configuration file that lets you run certain actions upon installation.

Full games/applications and DLC packages may both have install scripts. If you integrate your install scripts into your build, you may have any number of install scripts. For a SteamPlay app, it's recommended that you always use your OS-specific depots to contain your install scripts.

Example

A basic one will look like this:
"InstallScript" { "Registry" { "HKEY_LOCAL_MACHINE\\SOFTWARE\\Foo\\Bar" { "string" { "Install_Path" "%INSTALLDIR%" "Exe_Path" "%INSTALLDIR%\\foobar.exe" } "dword" { "PatchVersion" "12" } } } "Run Process" { "DirectX" { "HasRunKey" "HKEY_LOCAL_MACHINE\\Software\\Valve\\Steam\\Apps\\480" "Process 1" "%INSTALLDIR%\\DirectX\\DXSETUP.exe" "Command 1" "/silent" "NoCleanUp" "1" } } }

The second keyname after the root describes what kind of action will take place.

Note: All keynames and values can use escape sequences, so if you use a \, make it a \\.

Integrating Install Scripts into Your Build

First, the install script file must be part of a depot that is installed with the build. Ensure that the file resides within the defined ContentRoot of the App or Depot.

Second, mark an install script using the InstallScript directive in a depot build script. You can see an example on the Uploading to Steam - Advanced Build Scripts page.

During the build process, two things take place:
  • The install script is uploaded to Steam and cryptographically signed. This signature is validated by Steam before executing any install script, and is required to perform certain operations, including writing to the HKLM hive on Windows. This may cause your local copy of the install script to be modified.
  • The install script is marked in the depot manifest. You can see this in the generated manifest.txt file as a 100 in the Flags field.
When a Steam user is starting a game, Steam will scan all of the mounted depots for that game for any file with the install script flag and run them.

Registry

The Registry command allows you to create or modify string and dword registry values. Any key under the "Registry" keyname will be treated as the full path to the registry key you want to create or open. Under that key, specify either a "string" or "dword" key. Any keynames and values stored in the "string" or "dword" keys will be the registry names and values that get set.
To set the default value for a registry key, you should enter the key name as (Default).

Run Process

The Run Process command allows your application to run programs before the user first launches your game.
To determine whether the program needs to run, the install script looks at the keyname (as a registry DWORD value) in the HasRunKey value. If that value is not present or 0, then it will call CreateProcess on the processXX/commandXX values. If CreateProcess fails, then ShellExecuteEx is called. If the program's ExitCode is 0, then the install script assumes it was successful and writes your keyname as 1 in the registry.

Steam customers love a quick and silent install. Add silent or quiet parameters to all run process commands and only add what you absolutely need for the game.
The required Run Process key/values are:
  • Process 1 - Path to the program you want to launch
The optional Run Process key/values are:
  • Command 1 - Optional command you want to pass to the program.
  • HasRunKey - Optional registry key to check that the prereq is already installed.
  • NoCleanUp - Optional flag, when set install script will not delete the keyname when your app is deleted from Steam.
  • MinimumHasRunValue - Optional, sets the minimum value the install script should check for when determining to launch the program.
  • Requirement_OS - Optional key to apply OS requirements. See OS Specific Requirements for more details.
  • AsCurrentUser - Optional flag, set it to 1 if it's important for that program to run as the current user. Otherwise, the Steam client might run it as Administrator to avoid elevation prompts in Big Picture or VR environments.

Firewall Exceptions

If your game uses any networking, use the firewall exception to grant the firewall exception in windows automatically without forcing the user to accept the exception.
"Firewall" { "Space War Game" "%INSTALLDIR%\\SpaceWar.exe" }

OS Specific Requirements

The Requirement_OS value is available to run different installs on different OS versions / SKUs. It requires a new key group called Requirement_OS, then additional key value pairs inside. Available OS options are listed below.
  • Is64BitWindows - Specifies that the process will only run on a 64 bit version of the operating system. Values are 1 or 0.
  • OSType - Specifies that the process will only run on a specific version of the operating system. Values are:
    • Windows 3.11
    • Windows 95
    • Windows 98
    • Windows ME
    • Windows NT
    • Windows 2000
    • Windows XP
    • Windows 2003
    • Windows Vista
    • Windows 7
    • Windows 2008
    • Windows 2012
    • Windows 2012 R2
    • Windows 8
    • Windows 8.1
    • Windows 10

64 bit Example
This example will run the appropriate installer for the 32 or 64 bit installer.
"Net32" { "Process 1" "%INSTALLDIR%\\redist\\Controller\\32bitInstaller.exe" "NoCleanUp" "1" "Requirement_OS" { "Is64BitWindows" "0" } } "Net64" { "Process 1" "%INSTALLDIR%\\redist\\Controller\\64bitInstaller.exe" "NoCleanUp" "1" "Requirement_OS" { "Is64BitWindows" "1" } }

OS Type Example
This example will only run on Windows XP

"Controller" { "Process 1" "%INSTALLDIR%\\redist\\WinXPInstaller.exe" "NoCleanUp" "1" "Requirement_OS" { "OSType" "Windows XP" } }

Environment Variables

Environment variables are supported in an install script. All of the standard environment variables available on Windows can be used, along with a few others specific to an install script. They are:
  • %INSTALLDIR% - The full path to where the application is installed, without a backslash.
  • %ROOTDRIVE% - The drive letter to where the application is installed, like C
  • %APPDATA% - The \Users\username\AppData\ folder
  • %USER_MYDOCS% - Get the user\My Documents folder
  • %COMMON_MYDOCS% - Get the All Users\Documents folder
  • %LOCALAPPDATA% - \Documents and Settings\username\Local Settings\Application Data folder (only on Vista and Newer)
  • %WinDir% - Windows installation directory
  • %STEAMPATH% - The full path to the Steam client install directory.

Note that these are common paths, but they can be different based on what version of Windows the user is running.

Language Specific Values

Both string and DWORD values can be assigned different data depending on what language the user is running Steam in. To use, create a subkey in the "string" or "dword" key with the name of the language, then assign the names and values in there. For example:
"InstallScript" { "Registry" { "HKEY_LOCAL_MACHINE\\SOFTWARE\\MonkeyDime Studios\\Killer Banana Peel" { "dword" { "english" { "Language" "1" } "french" { "Language" "2" } "german" { "Language" "3" } "italian" { "Language" "4" } "spanish" { "Language" "5" } } } } }

The install script gets the language from Steam's registry key, querying the value "Language". If that value isn't found then "english" is the default.

Uninstallation of an app

When a user deletes or verifies your app from Steam, install scripts will be called to remove any registry values it created. The install script will also remove the value used to determine if a program should execute from Run Process, so that it can execute the next time your app runs (unless the NoCleanUp flag is set).

Run Process on Uninstall

If you need to run any process at the time your app is uninstalled, add this to the install script. Please do not uninstall common redists such as DirectX, msvc run time, etc, as they are likely to be used by other games. This is only intended for game specific uninstall processes.
NOTE: Run Process On Uninstall will also be called when a user verifies the app in Steam. Do not run a process that will delete all files, as this will cause Steam to redownload everything during a verify.
"InstallScript" { "Run Process On Uninstall" { "Process_name" { "Process 1" "process.exe" "Command 1" "/command" } } }

Frequently Asked Questions

Q. Why does my install script keep running my redistributable every time I launch the game?
A. This typically means that the redist is returning a non-zero return code. Steam checks that the return code is zero. If it sees that the return code is zero, it marks the redist as installed and doesn't run it again. If it returns any other value, Steam will attempt to run it again on next launch.

To fix this examine your redistributable paths and parameters. Some redists will return non-zero values if they already exist on the machine. This can often be fixed by using the redist's silent or quiet flag.

Q. Why doesn't my registry key get written?
A. Typically this is because the install script isn't signed and you're writing to HKLM.
See the section on build integration, and ensure that a "kvsignatures" key was added to your script during the build, as Steam requires this signing to be completed to write to HKLM.

This can also be caused by the Windows 64 bit virtualization on 64 bit Windows, Steam writes to the Wow6432Node path in the registry.

Q. Why doesn't my install script seem to run at all?
A. Please double check that your configuration is properly prepared.

Q. How do I add macOS redistributables? Why doesn't Run Process work in my macOS install script?
A. We don't currently have support for installing Mac redistributables. You will need to put the installer into your main executable.