This page shows how to download, install and run a Play application. There’s a built in tutorial that shows you around, so running this Play application will show you how Play itself works!
Play is a series of libraries available in Maven Repository, so you can use any Java build tool to build a Play project. However, much of the development experience Play is known for (routes, templates compilation and auto-reloading) is provided by SBT. In this guide we describe how to install Play with SBT. We also describe how to use Activator, an SBT wrapper that provides a graphical interface.
Play requires Java 1.8. To check that you have the latest JDK, please run:
If you don’t have the JDK, you have to install it from Oracle’s JDK Site.
§Installing Play with SBT
We provide a number of sample projects that have an
./sbt launcher in the local directory. These can be found on our download page. This launcher will automatically download dependencies without you having to install SBT ahead of time.
Refer to the SBT download page to install the SBT launcher on your system, which provides the
sbt command. Otherwise you can use the SBT launcher located in your example project’s directory.
§Running Play with SBT
SBT provides all the necessary commands to run your application. You can use
sbt run to run your app. For more details on running Play from the command line, refer to the new application documentation for more details.
§Installing Play with Activator
Activator is a wrapper for SBT that provides a nice graphical user interface and access to a library of third-party templates. Some new users prefer this interface to just using SBT. Note that since Activator is a wrapper for SBT, any commands referencing the
sbt command can also be used with the
For getting started, we’ll install Play through Lightbend Activator.
Activator can be described as “sbt plus templates” – it combines sbt (a build tool) plus a means of downloading project templates (like Maven archetypes) and a web interface for managing those projects. Templates can be examples, or they can be “seed” templates that provide a starting point for your own projects.
Activator comes with a couple of seed templates for Play that we recommend for getting started, play-scala and play-java.
Activator is distributed as a single archive file that expands out to its own subdirectory.
You can download Activator from https://playframework.com/download and click on the “offline distribution” link:
The “offline distribution” comes with all of Activator’s possible dependencies included. It’s a much larger initial download, but installing the offline distribution means that that starting up a new Play project is much faster, as all the dependencies are already resolved.
Extract the archive on a location where you have write access. Running
activator writes some files to directories within the distribution, so don’t install to
/usr/local or anywhere else you’d need special permission to write to.
§Adding Activator to your Path
For convenience, you should add the Activator installation directory to your system
§MacOS / Unix
Add to your login profile. Usually, this is
Make sure that the
activator script is executable. If it’s not:
chmod u+x /path/to/activator-x.x.x/bin/activator
In a command prompt, type:
Note that setx is only available on Windows 8 or later – before that, and you will have to use the System Properties dialog.
§Create a Project
Activator comes with a couple of different “seeds” that can be used to start off a Play project:
play-scala. You can create a project based off a template either from Activator’s Web Interface, or directly from the command line.
Open a command prompt, and type
activator ui to bring up the GUI interface. A browser window will open with the Web UI at http://localhost:8888.
Note: If you’re behind a proxy, make sure to define it with
set HTTP_PROXY=http://<host>:<port>on Windows or
export HTTP_PROXY=http://<host>:<port>on UNIX.
Follow the arrows to create a new project:
You can read the Activator documentation for more information on how to use the Web Interface.
§Accessing the Built-in Tutorial
Activator’s Web Interface contains a built in tutorial section that will walk you through your new application:
Play has an easy to use “development mode” that will let you make changes to code and see your results immediate on the page.
You can run Play in development mode from within Activator’s Web Interface by going to the Run tab and clicking the Run button:
This will bring up the Play application at http://localhost:9000.
You are now ready to work with Play! The next page will show you how to create projects from the command line and some more detail about creating new applications.
Next: Creating a new application
Found an error in this documentation? The source code for this page can be found here. After reading the documentation guidelines, please feel free to contribute a pull request.