Skip to main content

Configure Unicorn

Unicorn is single-threaded and multi-processed. It doesn't adjust the number of processes automatically based on traffic. You must use a unicorf.conf.rb or unicorn.conf.minimal.rb file, or a script, to configure this.

  • Example for unicorn.conf.rb:

    # Define your root directory.
    root = "/home/deployer/apps/gifroll/current"
    # Define worker directory for Unicorn.
    working_directory "/path/to/app/current"
    # Define number of worker processes.
    # Each forked OS process consumes additional memory.
    worker_processes 4
    # Define timeout for hanging workers before they are restarted.
    timeout 30
    # Location of PID file.
    pid "/path/to/app/shared/pids/"
    # Define log paths:
    # Allow redirecting $stderr to a given path. Unlike doing this from the shell,
    # this allows the Unicorn process to know the path being written to and rotates
    # the file if it is used for logging.
    stderr_path "#{root}/log/unicorn.log"
    # Same as stderr_path, except for $stdout. Not many Rack applications write
    # to $stdout, but any that do will have their output written here.
    stdout_path "#{root}/log/unicorn.log"
    # Loads Rails before forking workers for better worker spawn time.
    # Preloading your application reduces the startup time of individual
    # Unicorn worker_processes and allows you to manage the external connections
    # of each individual worker using the before_fork and after_fork calls.
    # Please check if other external connections work properly with
    # Unicorn forking. Many popular gems (dalli memcache client, Redis) will have
    # compatibility confirmation with Unicorn and the process model.
    # Check the gem documentation for more information.
    preload_app true
    # When enabled, Unicorn will check the client connection by writing the
    # beginning of the HTTP headers before calling the application. This will
    # prevent calling the application for clients who have disconnected while
    # their connection was queued.
    check_client_connection false
    # Enable a local variable to guard against running a hook (before_fork, after_fork)
    # multiple times
    run_once = true
    # For example, use of before_fork and after_fork:
    # POSIX Signals are a form of interprocess communication, and signal
    # events or state changes.
    # QUIT: Signals a process to exit, but creates a core dump.
    # TERM: Tells a process to terminate, but allows the process
    # to clean up after itself.
    # Unicorn uses the QUIT signal to indicate a graceful shutdown.
    # The master process receives it and sends it to all workers, telling them to
    # shutdown after any in-flight request.
    before_fork do |server, worker|
      Signal.trap 'TERM' do
        puts 'Unicorn master intercepting TERM and sending myself QUIT instead'
        Process.kill 'QUIT',
      # You may want to execute code in the master process, before the forking
      # begins, to deal with operations that causes changes in state.
      # You need them to run once:
      if run_once
        # do_something_once_here ...
        run_once = false # prevent from firing again
    after_fork do |server, worker|
      Signal.trap 'TERM' do
        puts 'Unicorn worker intercepting TERM and doing nothing. Wait for master to send QUIT'
      # ...
    # For more information, check the Unicorn Configurator:
  • Example for unicorn.conf.minimal.rb:

    listen 2007 # by default Unicorn listens on port 8080
    worker_processes 2 # this should be >= nr_cpus
    pid "/path/to/app/shared/pids/"
    stderr_path "/path/to/app/shared/log/unicorn.log"
    stdout_path "/path/to/app/shared/log/unicorn.log"

Configure forking

Unicorn has a multi-process architecture to make better use of available CPU cores. On startup, the Unicorn master process loads the application code and then spawns workers which inherit the application code from their master process. The requests are handled only by the workers and never by the master. The operating system network stack queues incoming requests and distributes them among the workers.

Unicorn is designed to replace crashed workers without dropping user requests. When a worker reaches the request timeout, the master process ends it (with kill -9) and replaces it with a new process. You can configure the number of worker processes and the request timeout.



worker_processes (nr)

Sets the current number of worker_processes to nr. Each worker process will serve exactly one client at a time. You can increment or decrement this value at runtime by sending signals SIGTTIN or SIGTTOU respectively to the master process without reloading the rest of your Unicorn configuration.

You can read more about signals on icon-external-link.svgUnicorn's site.


Sets after_fork hook to a given block


Sets before_fork hook to a given block.

Unicorn::Configurator#preload_app(bool) ⇒ ObjectEnabling

This preloads an application before forking worker processes. This allows memory savings when using a copy-on-write-friendly GC but can cause bad things to happen when resources like sockets are opened at load time by the master process and shared by multiple children.

Configure timeouts



Default value

timeout 30

This sets the timeout of worker processes to 30 seconds, the default value is 60 seconds. The timeout configuration will end workers that exceed this limit. This timeout is enforced by the master process itself and not subject to the scheduling limitations by the worker process.

60 seconds

delay integer

This sets the seconds to wait between successful tries.

0.5 seconds


Unicorn works with nginx for more settings.

Configure APMs

The following APMs support Unicorn:

See also