Sidekiq.cr: a Crystal port of the Sidekiq background job framework

Why a Crystal port of Sidekiq exists at all

Sidekiq is a background job framework for Ruby, and the port exists to offer the same idea to a different language. The stated reasoning is simple: Ruby is friendly and flexible but not terribly fast, while Crystal is statically typed, compiled and very fast while keeping a similar syntax to Ruby. The goal is to give Crystal applications a background worker that compiles to a single executable, which the project argues makes deployment easier than deploying Ruby.

That audience is narrow but real. A team that has already chosen Crystal for its web layer and needs to move long work off the request path will find the object model familiar if they know Sidekiq. A team starting from scratch has other options and no obligation to pick a port of a Ruby framework. Worth noting for expectations: the project is community supported and not commercially supported by @mperham and Contributed Systems, and the original Sidekiq was developed by Mike Perham, with this port maintained by Hugo Parente Lima.

Redis data compatibility is a hard requirement, API parity is not

The design rule that shapes the whole port is stated without ambiguity: the Ruby and Crystal versions of Sidekiq must remain data compatible in Redis, and both versions should be able to create and process jobs from each other. That is a stronger constraint than a typical client library, because it means the wire format of a job is fixed by the Ruby implementation and the Crystal code has to read and write it exactly.

The corollary is equally explicit. The APIs are not and should not be identical, but should rather be idiomatic to their respective languages. So a Crystal developer gets a Crystal-shaped API, not a transliteration of the Ruby one, and a mismatch in method names is a deliberate choice rather than a porting bug. The practical consequence for an adopter is that a mixed deployment works, but a team that writes its job payloads by hand against one language's API still has to confirm the fields the other side expects. The naming itself is a trademark matter: Sidekiq is a registered trademark of Contributed Systems, who granted use of the name to this project.

Building and starting the worker through the Makefile

The repository ships a Makefile whose targets cover the whole local workflow. Dependencies are resolved with the Crystal shard tool, and the spec suite runs with crystal spec:

prepare:
	shards

test:
	crystal spec

The two example programs are separate processes. The worker is examples/sidekiq.cr and the web interface is examples/web.cr:

run:
	crystal run examples/sidekiq.cr

web:
	crystal run examples/web.cr

For deployment the project builds optimized single binaries instead of running from source:

bin: clean
	time crystal build -s --release -o sidekiq examples/sidekiq.cr
	time crystal build -s --release -o sideweb examples/web.cr

The examples directory also holds sidekiq.service and sidekiqweb.service, which are systemd unit files matching the daemonization approach the project asks you to use. The README does not document the exact command line flags for the worker, so the in-depth documentation lives in the project wiki rather than in the repository README.

Running jobs inline in specs instead of pushing them to Redis

The testing section explains how to keep a spec from reaching Redis. Requiring sidekiq/testing turns on Sidekiq.testing, which lets a spec control how pushed jobs behave instead of always hitting the queue:

require "sidekiq/testing"

Sidekiq.testing(Sidekiq::TestMode::Inline)

HardWorker.async.perform(1_i64)

The mode enum has two values. Disable is the default, where Sidekiq behaves normally and jobs are pushed to Redis. Inline means jobs are executed synchronously, in process, the moment they are pushed rather than being enqueued. A detail worth knowing before you rely on it: perform_at and perform_in do not make sense while Inline is active, and using them raises an exception.

The mode can also be scoped to a block, in which case it is active only for the duration of the block and whatever mode was active before is restored afterwards:

Sidekiq.testing(Sidekiq::TestMode::Inline) do
  HardWorker.async.perform(1_i64)
end

The block form is the safer one to reach for by default, because it does not leave global state behind for the next spec file.

The test mode flag is process-wide and not thread-safe

The README carries an explicit warning about the testing flag that is easy to skim past. Sidekiq.test_mode is a single, process-wide flag, and mutating it is not thread-safe. Specs that rely on it should not run concurrently across fibers or threads, for example with -Dpreview_mt or a parallel spec runner, because one spec's mode can leak into another's.

That constraint has direct consequences for how you structure a suite. If a project runs specs in parallel, switching the mode per example is a source of intermittent, order-dependent failures rather than a convenience. The block form narrows the window but does not remove the shared flag, so the practical answer is to keep the mode stable for a whole file or group of files that must not overlap, and to treat any attempt at per-example mode switching under a parallel runner as unsupported. The README does not document a per-worker or per-connection alternative, so there is no other switch to reach for here.

Daemonization, pidfiles, log rotation and delayed extensions are out of scope

The project lists what it will not build, and the list is worth reading before you pick it. Support for daemonization, pidfiles and log rotation will not exist, and the recommendation is to use Upstart or Systemd for that. The reason is architectural rather than a missing feature: a Crystal service already compiles to a single executable, so the supervisor's job is to run that binary, and the systemd unit files in the examples directory exist for exactly that reason.

The second exclusion is scheduled or delayed work, described as delayed extensions and called too dynamic for Crystal. This is the sharpest functional gap in the port. A background job framework that cannot defer a job until a future time removes a feature many queues are bought for, and there is no adapter, cron shim or documented workaround in the repository to compensate. If your use case is reminders, billing retries on a schedule, or anything that must run at a given hour, Sidekiq.cr cannot serve it on its own.

The benchmark table in the README is old and self-described as rough

The performance argument for the port rests on a table the project itself labels rough and initial, measured on macOS 10.14.5 with ruby 2.7.2. Sidekiq 6.2.0 is listed at 55MB RSS, 16.4 time and 6,100 jobs per second, Sidekiq 6.2.0 with hiredis at 49MB, 13.0 and 7,900 jobs per second, and Crystal 0.35.1 at 15MB, 3.8 and 26,000 jobs per second.

Two things follow from those numbers, and neither is a benchmark you can rely on today. The Crystal compiler version in the table is 0.35.1, which is far behind the current release, and the Ruby comparison is a specific Sidekiq 6.2.0 build with a specific redis client. The measurement is also a throughput figure for a synthetic job loop under the bench directory, not a measurement of your own workload, and it says nothing about latency per job or behaviour under Redis contention. Treat the table as the project's motivation, not as a capacity plan.

Community maintenance, an LGPL-3.0 licence and a two-year release gap

The maintenance picture comes from the repository itself. The project is not archived, and the last push was on 2026-07-31, with release v0.8.0 published on 2026-07-08. Before that, v0.7.2 dates from 2023-04-19 and v0.7.1 from 2023-04-02, so the visible release history is one recent release after a gap of more than three years, and the port has been maintained by a single person with community contributions rather than by the Ruby original's company. General maintenance and bug fixes are welcomed, and the issues list is where chores are tracked.

The licence is LGPL-3.0, which carries the usual obligations for a library that is linked into an application, and this is not legal advice. The name Sidekiq is granted by trademark rather than by the licence, so the licence and the trademark are two separate permissions to check. In practice the upgrade cost is low if you stay on one version, and non-trivial if you cross the 2023 to 2026 boundary, where API and constructor changes accumulated without a release each time.

Editorial conclusion

Sidekiq.cr is worth a look for a Crystal service that already has Redis and wants a compiled job worker, especially where a Ruby and Crystal deployment share one queue, and it is a poor match for a team that needs scheduled or delayed jobs, daemonization, or a vendor-backed support contract. Before committing, read the wiki for the Crystal API, confirm the current version in shard.yml against the release you target, and check that the Redis payload format your Ruby side already writes can be read by the Crystal worker.

Frequently asked questions

Official sources

1. hugopl/sidekiq.cr on GitHub
2. License: LGPL-3.0
3. Project website
4. README
5. Releases