Skip to content
Get packs

Guide · Open source

How to use WinSW: run any app as a Windows service

Updated · written with AI from the project's own documentation and checked against our catalogue data

WinSW is a small wrapper executable that runs any application as a Windows service, so the program starts with the machine and keeps running without a logged-in user. It is aimed at developers and teams who deploy servers or console programs such as Java applications on Windows. After this guide you will know how to write a service XML file, install the service, and start and check it from the command line.

WinSWwinsw/winsw · ★ 14.4k · MIT

Quick start

  1. 1Check prerequisites. Confirm the machine has .NET Framework 4.6.1 or later, or use the bundled .NET 7 executables.
  2. 2Get WinSW. Download WinSW.exe or WinSW.zip from GitHub Releases.
  3. 3Write the XML file. Create myapp.xml with id, name, executable and arguments, following the specification.
  4. 4Install the service. Run winsw install myapp.xml from an administrator prompt.
  5. 5Start the service. Run winsw start myapp.xml to launch it.
  6. 6Check the status. Run winsw status myapp.xml to confirm it is running.

Check the requirements before you start

WinSW 3 runs on Windows systems that have .NET Framework 4.6.1 or later installed. .NET Framework is preinstalled since Windows 10, version 1511 and Windows Server 2016, and installable since Windows 7 SP1 and Windows Server 2008 R2 SP1.

For systems without .NET Framework, the project provides native 64-bit and 32-bit executables based on .NET 7.

  • .NET Framework 4.6.1 or later, or the bundled .NET 7 executables
  • Windows with administrator rights for most commands

Download WinSW and get the files

WinSW binaries are available on GitHub Releases, which contains stable 2.x releases and 3.x pre-releases. NuGet and Maven packages currently correspond to 2.x. The project's README also shows cloning the repository with git clone https://github.com/winsw/winsw.

Development of WinSW 3.x happens on the default branch v3. For 2.x documentation, refer to the v2 branch.

  • Take WinSW.exe or WinSW.zip from the distribution
git clone https://github.com/winsw/winsw

Write the XML configuration file

WinSW is managed by an XML configuration file. You describe the program, its arguments and logging in this file. Place it next to the wrapper so WinSW can find it.

The README sample runs Jenkins through Java. The id and name identify the service, executable and arguments say what to run, and the log element sets logging mode. The full specification is in docs/xml-config-file.md.

  • id: the service identifier
  • name: the display name
  • executable: the program to run, here java
  • arguments: the command-line arguments
  • log mode: set to roll in the sample
  • %BASE%: a placeholder for the folder that holds the config
<service> <id>jenkins</id> <name>Jenkins</name> <description>This service runs Jenkins continuous integration system.</description> <env name="JENKINS_HOME" value="%BASE%"/> <executable>java</executable> <arguments>-Xrs -Xmx256m -jar "%BASE%\jenkins.war" --httpPort=8080</arguments> <log mode="roll"></log> </service>

Install and start the service

There are two ways to set it up. In the global tool approach, run winsw install myapp.xml [options] to install, then winsw start myapp.xml to start. In the bundled approach, rename WinSW.exe to something like myapp.exe, place it side by side with myapp.xml, and run myapp.exe install and myapp.exe start.

Run winsw status myapp.xml, or the bundled equivalent, to see whether the service is up and running.

  • Global tool: winsw install, winsw start, winsw status
  • Bundled: myapp.exe install, myapp.exe start
  • Most commands need Administrator privileges; WinSW prompts for UAC in non-elevated sessions
winsw install myapp.xml [options] winsw start myapp.xml winsw status myapp.xml

Manage the service with the main commands

WinSW accepts a set of commands on the renamed executable. Use stop, restart, uninstall, refresh and customize to manage the service over its life. The refresh command updates service properties without reinstalling.

Three experimental dev commands exist: dev ps draws the process tree, dev kill terminates a service that has stopped responding, and dev list shows services managed by the current executable.

  • install, uninstall, start, stop, restart, status
  • refresh: update properties without reinstallation
  • customize: customizes the wrapper executable
  • dev ps, dev kill, dev list (experimental)

Learn the advanced features

The documentation covers self-restarting services, deferred file operations, logging and error reporting, and extensions. Read the troubleshooting page if the service does not start as expected.

If you are moving from WinSW 2.x, the project has a migration guide for 3.x.

  • Self-restarting services
  • Deferred file operations
  • Logging and error reporting
  • Extensions
  • Troubleshooting
  • Migrate to WinSW 3.x

What people use it for

  • Running a Jenkins server as a background service on a Windows machine
  • Deploying a Java application (.jar) so it starts with the machine
  • Keeping a console program running without a logged-in user
  • Running a server process on Windows servers managed by a team

Frequently asked questions

Is WinSW free to use?

Yes. WinSW is licensed under the MIT license, which is a permissive open-source license. The license text is in the project's LICENSE.txt file.

What does WinSW require to run?

WinSW 3 needs .NET Framework 4.6.1 or later. For systems without it, the project provides native 64-bit and 32-bit executables based on .NET 7.

Does WinSW have a graphical interface?

The README describes command-line and XML-based management. It does not describe a GUI, so you manage services through the commands and the XML file.

Can I run a Java app as a Windows service with WinSW?

Yes. The README sample runs Jenkins by setting the executable to java and passing the .jar file in the arguments element of the XML file.

Do I need to be an administrator?

Most commands require Administrator privileges. WinSW prompts for UAC when run from a non-elevated session.

What are the alternatives to WinSW?

The README lists srvany.exe, nssm, srvany-ng and shawl as similar projects. Compare them on license, requirements and the features you need before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

WinSW suits developers and teams who need a server or console program to run as a Windows service under a permissive MIT license, and who are comfortable with XML and the command line. If you only need an app to start at login, or you need a graphical tool, or you work on Linux or macOS, choose a different option.

Install options & downloads