Easy to use classic captcha for Rails apps

Example of captcha field


  • Configurable via DSL

  • Supports caching

  • Simple, Easy to use

  • Uses Imagemagick via the MiniMagick gem


Add this line to your application's Gemfile:

gem 'captcher'

And then execute:

$ bundle

Or install it yourself as:

$ gem install captcher

Mount the engine inside your application by adding this line to your application's routes file at config/routes.rb:

mount Captcher::Engine => "/captcher"


Render on page

  1. Include the concern with helper methods to your ApplicationController:

class ApplicationController < ActionController::Base
  include Captcher::CaptchaAware

  1. Use helper methods in your controller:

class MyController < ApplicationController
  def index
    reload_captcha # Reload the captcha
    # render response with success code ...

  def create
    @comment =
    captcha_check = confirm_captcha?(params[:captcha])
    if @comment.valid? && captcha_check &&
      # render response with success code ...
      @comment.errors[:captcha] << "Captcha verification failed" unless captcha_check
      # render response with error code ...

  # ... some other code

  1. An example bootstrap-based html/erb code:

<%= simple_form_for(some_form) do |f| %>
  <!-- Some html/erb code for all form fields -->
  <!-- ... -->
  <!-- /Some html/erb code for all form fields -->

  <div class="input-group">
    <%= text_field_tag :captcha, "",
      type: :text,
      label: false,
      class: "form-control",
      placeholder: "Enter the captcha" %>

    <div class="input-group-append">
      <div class="input-group-text" style="padding: 0">
        <%= image_tag(captcher.captcha_path(format: :png), style: "height: 35px;",
                                                           id: "captcha-image") %>
      <button class="btn btn-outline-secondary" type="button" id="captcha-reload">
        <i class="fa fa-refresh"></i>

<% end %>

  1. Javascript code to refresh the capture:

function reloadCaptcha() {
    type: 'GET',
    url: '/captcher/captcha/reload.png',
    success: function() {
      var timestamp = (new Date()).getTime();
      $('#captcha-image').attr("src", "/captcher/captcha.png?" + timestamp);

$('#captcha-reload').click(function() {

API endpoints

These endpoints are available by default (as soon as you've mounted the Captcher engine to your routes.rb file) and can be used for some async requests:

  • - Load the captcha image

  • - Reload the captcha

  • - Confirm captcha code


Select one of the following available modes:

  • code_captcha - Classic image-based captcha;

  • cached_captcha - Acts like a caching proxy for any of available captcha types. Keeps several generated captcha variants in cache. The number of available cache slots is configured with the slots_count parameter

  • math_captcha (not implemented yet)

  • awesome_captcha (not implemented yet)

# config/initialiers/captcher.rb

Captcher.configure do |c|
  c.mode = :cached_captcha

  c.code_captcha do |cc|
    cc.fonts        Dir[Captcher::Engine.root.join("lib/fonts/**")]
    cc.font_size    50
    cc.font_color   "black"
    cc.count        5
    cc.background   "#999999"
    cc.format       "png"

  c.cached_captcha do |cc|
    cc.slots_count 10
    cc.wrapped     :code_captcha


  1. Implement some other types of captcha

  2. Integrate with Travis to test the gem against different versions of Ruby/ROR

  3. Improve code style

  4. Improve documentation

  5. Autogenerated API documentation

  6. ~~Add some caching~~


Contribution directions go here.


The fonts wich are shiped by default with this repo are taken from and use the SIL Open Font License, v1.1

There's a list of the origin paths of the fonts:


The gem is available as open source under the terms of the MIT License.