Guide · Open source

How to use Capistrano: install, write tasks and deploy

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

Capistrano is a framework for writing automated deployment scripts. You run the cap command, it connects to your servers over SSH, and it runs the steps needed to deploy your project. This guide is for developers who already deploy by logging into servers over SSH and want to repeat that process reliably. By the end you will know what to install, how to generate the starter files, and how to run a deployment to a stage.

Capistranocapistrano/capistrano · ★ 13k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm Ruby 2.5 or higher, a source-controlled project, SCM binaries on the server, and working key-based SSH login.
2Add the gem. Add gem "capistrano", "~> 3.17", require: false to a development group in your Gemfile.
3Install gems. Run bundle install to download and install Capistrano.
4Generate config files. Run bundle exec cap install in your project, after confirming no Capfile already exists.
5Edit deploy.rb and stage files. Replace template values with your project settings and your target server details.
6Write or add tasks. Define any extra steps, such as restarting a service, as Rake tasks and hook them in with after.
7Dry-run then deploy. Run cap production deploy --dry-run first, then run cap production deploy when the output looks right.

What do you need before you install Capistrano?

Capistrano needs Ruby version 2.5 or higher on your local machine (MRI or Rubinius). Your project should use source control: Git, Mercurial, and Subversion support is built in. The SCM binaries, such as git or hg, must be installed on the servers you deploy to.

Capistrano also depends on key-based, passwordless SSH login. The README says you need this working before you can use Capistrano.

Ruby 2.5 or higher on your local machine
A project that uses source control (Git, Mercurial, or Subversion)
SCM binaries such as git or hg installed on the target servers
Bundler and a Gemfile are recommended

How do you install the Capistrano gem?

Add Capistrano to your project's Gemfile inside a development group, using require: false. Then run Bundler so the gem is downloaded and installed.

group :development do
  gem "capistrano", "~> 3.17", require: false
end

$ bundle install

How do you generate Capistrano config files with cap install?

Make sure your project does not already have a Capfile or capfile. Then run the install command. It creates the configuration files and directory structure for two stages, staging and production. To choose different stages, pass a STAGES list.

The generated files are templates. Edit deploy.rb and the stage files so they contain values that fit your project and your target servers.

Capfile
config/deploy.rb
config/deploy/staging.rb and config/deploy/production.rb
lib/capistrano/tasks

$ bundle exec cap install
$ bundle exec cap install STAGES=local,sandbox,qa,production

How do you write deployment tasks?

Capistrano runs tasks written as Rake tasks. You can write your own steps or use pre-built task libraries from the Capistrano community. Out of the box, Capistrano deploys your code but does not know how to execute it, so you must tell it things like whether foreman needs running or Apache needs restarting.

The example below defines a task that restarts Sidekiq on servers tagged with the worker role, then runs after the deploy:published step.

Use roles(:worker) to limit a task to servers with that role
Use execute to run a command on the remote server
Use after to hook a task into the deploy flow

task :restart_sidekiq do
  on roles(:worker) do
    execute :service, "sidekiq restart"
  end
end
after "deploy:published", "restart_sidekiq"

How do you deploy to a stage?

Run cap with the stage name and the deploy task. Use cap -T to list every available task. Before a real deployment, use the --dry-run flag, which simulates the deployment and does not actually do anything.

When something behaves unexpectedly, the flags --prereqs, --trace, and --print-config-variables help you see task dependencies, task invocations, and config values before deployment tasks run.

cap -T lists all available tasks
--dry-run simulates a deployment without running it
--prereqs lists task dependencies
--trace shows task invocations
--print-config-variables lists config variables before deployment tasks

$ bundle exec cap -T
$ bundle exec cap staging deploy
$ bundle exec cap production deploy
$ bundle exec cap production deploy --dry-run
$ bundle exec cap production deploy --prereqs
$ bundle exec cap production deploy --trace
$ bundle exec cap production deploy --print-config-variables

Where can you get help with Capistrano?

The docs directory in the repository holds the official documentation. The project also points to a Stack Overflow Capistrano tag and a low-traffic mailing list monitored by contributors. Capistrano is built from several repositories, and the README names sshkit, which provides the SSH behavior underneath execute, and airbrussh, which provides default log formatting.

Official docs in the docs directory
Stack Overflow tag: capistrano
Capistrano mailing list
sshkit provides SSH behavior used by execute

What people use it for

Deploying the same Rails app to staging and production with different server IP addresses per stage
Restarting a background job service such as Sidekiq on worker servers after each deploy
Running different tasks on app servers and web servers by tagging them with roles
Using a community gem that adds deployment tasks for a framework such as Rails

Frequently asked questions

Is Capistrano free to use?

Capistrano is released under the MIT licence, as listed in the project details. The README does not mention paid tiers, so you can use it as the licence allows.

What are the requirements for Capistrano?

You need Ruby 2.5 or higher on your local machine, a project that uses source control, and the SCM binaries such as git on your servers. Bundler and a Gemfile are recommended, and key-based passwordless SSH login is required.

Can Capistrano deploy projects that are not Ruby or Rails?

Yes. The README says Capistrano is written in Ruby but can deploy projects of any language or framework, including Rails, Java, or PHP.

Does Capistrano set up my servers?

No. The README says server provisioning, such as installing databases, web servers, or language runtimes, is not done by Capistrano. Capistrano itself needs only SSH.

Can Capistrano handle sudo or interactive prompts?

The README says Capistrano is designed for a single non-privileged SSH user in a non-interactive session. Deployments needing sudo or prompts can sometimes be done, but it may be difficult.

How is Capistrano different from Ansible, Kamal, Fabric, or Mina?

The source does not compare these tools in detail. It only notes that Capistrano relies on SSH commands and does not provision servers. Check each tool's documentation to compare features for your setup.

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

Capistrano suits developers who already deploy over SSH and want that process repeated across stages and server roles. It is a poor fit if you are uncomfortable on the Linux command line, cannot use key-based SSH login, or need a tool that also provisions servers.

Install options & downloads