2.31
No release in over 3 years
Puma is a simple, fast, threaded, and highly concurrent HTTP 1.1 server for Ruby/Rack applications. Puma is intended for use in both development and production environments. It's great for highly concurrent Ruby implementations such as Rubinius and JRuby as well as as providing process worker support to support CRuby well.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Runtime

~> 2.0
 Project Readme

Puma logo

Puma: A Ruby Web Server Built For Parallelism

Actions

Official merch on commitgoods.com

Puma is a simple, fast, multi-threaded, and highly parallel HTTP 1.1 server for Ruby/Rack applications.

Built For Speed & Parallelism

Puma is a server for Rack-powered HTTP applications written in Ruby. It is:

  • Multi-threaded. Each request is served in a separate thread. This helps you serve more requests per second with less memory use.
  • Multi-process. "Pre-forks" in cluster mode, using less memory per-process thanks to copy-on-write memory.
  • Standalone. With SSL support, zero-downtime rolling restarts and a built-in request bufferer, you can deploy Puma without any reverse proxy.
  • Battle-tested. Our HTTP parser is inherited from Mongrel and has over 15 years of production use. Puma is currently the most popular Ruby webserver, and is the default server for Ruby on Rails.

Originally designed as a server for Rubinius, Puma also works well with Ruby (MRI) and JRuby.

On MRI, there is a Global VM Lock (GVL) that ensures only one thread can run Ruby code at a time. But if you're doing a lot of blocking IO (such as HTTP calls to external APIs like Twitter), Puma still improves MRI's throughput by allowing IO waiting to be done in parallel. Truly parallel Ruby implementations (TruffleRuby, JRuby) don't have this limitation.

Quick Start

$ gem install puma
$ puma

Without arguments, puma will look for a rackup (.ru) file in the working directory called config.ru.

SSL Connection Support

Puma will install/compile with support for ssl sockets, assuming OpenSSL development files are installed on the system.

If the system does not have OpenSSL development files installed, Puma will install/compile, but it will not allow ssl connections.

Frameworks

Rails

Puma is the default server for Rails, included in the generated Gemfile.

Start your server with the rails command:

$ rails server

Many configuration options and Puma features are not available when using rails server. It is recommended that you use Puma's executable instead:

$ bundle exec puma

Sinatra

You can run your Sinatra application with Puma from the command line like this:

$ ruby app.rb -s Puma

In order to actually configure Puma using a config file, like puma.rb, however, you need to use the puma executable. To do this, you must add a rackup file to your Sinatra app:

# config.ru
require './app'
run Sinatra::Application

You can then start your application using:

$ bundle exec puma

Configuration

Puma provides numerous options. Consult puma -h (or puma --help) for a full list of CLI options, or see Puma::DSL or dsl.rb.

You can also find several configuration examples as part of the test suite.

For debugging purposes, you can set the environment variable PUMA_LOG_CONFIG with a value and the loaded configuration will be printed as part of the boot process.

Documentation

Platform Constraints

Some platforms do not support all Puma features.

  • JRuby, Windows: server sockets are not seamless on restart, they must be closed and reopened. These platforms have no way to pass descriptors into a new process that is exposed to Ruby. Also, cluster mode is not supported due to a lack of fork(2).
  • Windows: Cluster mode is not supported due to a lack of fork(2).
  • Kubernetes: The way Kubernetes handles pod shutdowns interacts poorly with server processes implementing graceful shutdown, like Puma. See the kubernetes section of the documentation for more details.

Merchandise

Puma stickers, shirts, hoodies, and mugs are available at commitgoods.com.

Contributing

Find details for contributing in the contribution guide.

License

Puma is copyright Evan Phoenix and contributors, licensed under the BSD 3-Clause license. See the included LICENSE file for details.

Puma includes a copy of sd_notify (commit cca575c), licensed under the MIT license. See lib/puma/sd_notify.rb for the license text.