Scroll to navigation

PUMA(1) User Commands PUMA(1)


puma - fast, concurrent web server for ruby and rack


puma [options...] [rackup file]

puma [-h | --help | -V | --version]


The following options are available:

URI to bind to (tcp://, unix://, ssl://).
Load given path as a config file.
DEPRECATED alias for --control-url.
The TOKEN to use as authentication for the control server.
The bind URL to use for the control server and app. Use auto to use a temp unix server. This requires to use a --control-token, which needs to be given with every request to the control server (token=foo).
Demonize the server into the background.
Show low level debugging information.
Change to given directory before starting.
The environment to run the Rack app on. Default development.
Specify $LOAD_PATH directories.
Define the TCP port to bind to. Use -b for more advanced options.
Use the given path as PID file.
Preload the application. This loads all the application code prior to forking. Preloading reduces total memory usage of an application and is only available in cluster mode.
Prune out the bundler env if possible.
Do not log requests internally. Default: true.
Log requests as they occur.
The puma command to run during a hot restart. Default: inferred.
Where to store the state details.
Min:max threads to use. Puma will automatically scale the number of threads, from the minimum until it caps out at the maximum, based on how much traffic is present. Default: 0:16.
Run the app in raw TCP mode instead of HTTP mode.
Enable early hints support.
Activate cluster mode and define number of worker processes to create. In this mode workers are forked from a master process. Each child process still has its own thread pool and the -t setting is per worker.
Additional text to display in process listing.
Redirect STDOUT to a specific file.
Redirect STDERR to a specific file.
Append to redirected files.
Show help.
Print the version information.


The following examples show how to bind TCP or sockets:

Bind Puma to a socket with the -b (or --bind) flag:

To use a UNIX Socket instead of TCP:

To change the permissions of the UNIX socket, add a umask parameter:

In need of a bit of security use SSL sockets:

The following example show how to Create a control server and use pumactl(1) to interact with the control server to restart puma.

puma --control-url tcp:// --control-token foo
pumactl --control-url 'tcp://' --control-token foo restart


puma will look for a configuration file at config/puma.rb. If an environment is specified, either via the -e and --environment flags, or through the RACK_ENV or the RAILS_ENV environment variables, it looks for configuration at config/puma/<environment_name>.rb.

The -C flag allows one to pass on a custom configuration location. If the value specified is a dash (-) puma won't look for any configuration file:

puma -C "-"


There is extensive documentation at <> and <>.


This manual page was written by Daniel Leidert <>, for the Debian GNU/Linux system (but may be used by others).

January 2020 PUMA 3.12