Barby: a Ruby library for generating barcodes, split by symbology and output format

What Barby is and how the two halves fit together

Barby is a Ruby library that generates barcodes in a variety of symbologies, and its functionality is split into barcode and outputter objects.

Barby::Barcode objects turn data into a binary representation for a given symbology. Barby::Outputter then takes that representation and turns it into images, PDF, and so on.

That split is the whole design, and it is the reason to use the library at all. The README explains the payoff in both directions: you can easily add a symbology without having to worry about graphical representation, and if it can be represented as the usual 1D or 2D matrix of lines or squares, the outputters will do that for you. Likewise, you can easily add an outputter for a format that does not have one yet, and it will work with all existing symbologies.

So there are two independent extension axes. A symbology author writes only about encoding. A format author writes only about rendering. Neither has to know what the other does.

The library is MIT licensed, published as a gem, and the repository describes itself as the Ruby barcode generator. The homepage is the project's GitHub pages site, and the wiki holds the fuller documentation.

The example in the README is short enough to show the whole API surface:

require 'barby'
require 'barby/barcode/code_128'
require 'barby/outputter/ascii_outputter'

barcode = Barby::Code128B.new('BARBY')

puts barcode.to_ascii #Implicitly uses the AsciiOutputter

The comment on the last line records a convenience worth knowing about: calling to_ascii on the barcode picks the outputter for you, so the explicit require in that example is not strictly needed for the call to work. It is still the recommended style, because an implicit outputter lookup that depends on what has been loaded is the kind of thing that breaks when a file is refactored.

The require policy change, and what it means for an existing codebase

The README has a section headed New require policy, and it is the single most consequential operational detail for anyone adopting the library.

Barcode symbologies are no longer required automatically, so you have to require the ones you need. If you need EAN-13, you require 'barby/barcode/ean_13'. There is a full list of symbologies and filenames below.

The reason for the change is the obvious one once stated: loading every symbology means loading their dependencies, and three of them depend on native code. A QR Code require pulls in rqrcode, DataMatrix pulls in dmtx, and PDF417 requires JRuby. If requiring 'barby' loaded all of them, every user of the library would need those native dependencies installed even if they only wanted Code 128.

The practical consequence for an existing project is that upgrading is a code change, not just a version bump. Code that relied on the old implicit loading will raise a missing constant or an uninitialised constant at runtime rather than at boot, because the failure only occurs when the specific symbology class is first referenced. That is a worse failure mode than a load error, and it is the kind of thing worth searching for before upgrading rather than after.

The symbiology table also uses the same filename convention, so the require line and the table entry match: ean_13 for EAN-13, code_128 for Code 128, qr_code for QR Code, data_matrix for DataMatrix and pdf_417 for PDF417.

The outputter side follows the same convention with an _outputter suffix, so ascii_outputter, svg_outputter, png_outputter and the rest.

The symbology table and which formats need native code

Thirteen symbologies are listed, and most of them come with no dependencies at all.

The Code 25 family has Interleaved and IATA variants. Code 39 has an Extended variant. Code 93 and Code 128 with its A, B and C subsets and a GS1 128 variant are there. Codabar, EAN-13 with Bookland and UPC-A variants, EAN-8, and the UPC/EAN supplemental in two and five digit forms are all dependency-free.

Then the three that are not. QR Code needs rqrcode. DataMatrix, the dmtx format, needs dmtx. PDF417 needs JRuby.

The last one is the unusual case. A PDF417 symbology requiring JRuby means that output format is not available on CRuby at all, which is a much bigger constraint than a gem dependency. It is the kind of thing to check early, because a project that assumes PDF417 will work everywhere will discover otherwise late.

It is also worth reading the table as a coverage map rather than a list. Barby covers the retail and logistics symbologies comprehensively, the Code 25 and Code 39 families with their variants, the GS1 family, and the two most common 2D formats. What is absent from the visible list is anything like Data Matrix ECC 200, Aztec or MaxiCode, and it is worth checking the wiki for the current list rather than assuming the README table is exhaustive.

The codes are worth distinguishing from the symbology names, because the table shows where a filename serves more than one name. Code 39 Extended is listed with the filename code_39, and UPC-A is listed with the filename ean_13, because both are variants computed from the same encoding logic. That is a sensible consolidation and a small trap for anyone scripting against filenames, since the filename is not always a transliteration of the display name.

The outputters and the formats they produce

Seven outputters are listed, and three of them need a dependency.

The ascii outputter needs nothing and produces text, which the README describes as mostly for testing. The html outputter needs nothing. The pdfwriter outputter needs nothing, which is worth noting since it means PDF generation does not require a native library. The svg outputter needs nothing.

The three that do need something are png, which requires chunky_png, prawn, which requires prawn, and rmagick, which requires rmagick. The rmagick case is the one to look at, because ImageMagick is a system-level dependency with its own security history and its own installation requirements, and a Ruby gem that shells out to it inherits all of that.

The format list underneath is the summary of what the outputters between them can produce: text, mostly for testing; PNG, JPEG and GIF; PS and EPS; SVG; PDF; and HTML. Note that JPEG and GIF appear in the format list without a dedicated outputter, which means they are reached through one of the others rather than having their own entry.

The dependency choices tell a story about how the library grew. chunky_png is a pure-Ruby PNG encoder, so the png outputter avoids a native dependency entirely. prawn is a pure-Ruby PDF generator, so the pdfwriter outputter does the same. The two entries that do reach for native code are the ones where a pure-Ruby implementation was not viable.

The README's closing advice is to check out the Barby wiki for more information, with separate pages linked for symbologies and for outputters, which is where the per-format details live.

Limits: a fixed symbology set, old dependencies and a small release history

The limits are worth knowing before you choose it.

The first is that the symbology list is fixed at what the table shows. Adding a symbology means writing the encoder yourself, which the README explicitly welcomes, but a symbology like Aztec or a GS1 variant with specific application identifiers is real work rather than configuration.

The second is the dependency situation for three of the symbologies and three of the outputters. rqrcode, dmtx and JRuby for symbologies, chunky_png, prawn and rmagick for outputters. The pure-Ruby ones are unremarkable. The native ones are the risk: rmagick in particular drags in ImageMagick, and if your deployment is a slim container or a platform where ImageMagick is awkward to install, that outputter is not available to you.

The third is the age of the release history. The single tagged release is v0.5.1 from 2013-08-15, while the last push to the repository was on 2026-09-28. So there is a long gap between the newest tag and the newest commit. The CHANGELOG is in the repository root rather than under docs, and the tree also has a Rakefile, a barby.gemspec, a Gemfile, a test/ directory, a lib/ directory, a bin/ directory and a vendor/ directory.

That gap is a double-edged fact. It suggests the project is stable and the public API is unlikely to churn, which for a barcode library is a virtue. It also means the last published gem version may predate work in the repository, so if you need something that appears in the recent commits you may find yourself depending on the git source rather than the released gem.

The fourth is that the library is deliberately narrow. It generates barcodes. It does not scan them, it does not render Code 128 as a font, and it does not handle GS1 application identifiers or produce the human-readable HRI digits that a retail scanner expects to see under a barcode. For a shipping label workflow, those omissions are the ones that matter, and the README does not claim to cover them.

Barby against a barcode font and against a service-side image API

Two comparisons make the choice clearer.

The first is against a barcode font. Rendering a barcode as text with a specialised font is the classic approach and it has one enormous advantage: no image pipeline. The barcode is text, it flows in a document, it scales, and it prints. The costs are that the font has to be installed wherever the document is rendered, that the symbol widths are fixed by the font design rather than by the symbology rules, and that you have very little control over the output.

Barby sits on the other side of that trade. You get real encoders, so the barcode is correct by construction, and you get a choice of output formats from plain ASCII through SVG and PDF to PNG. The cost is that you now have an image or vector pipeline in your application, which is a dependency you did not have before.

For a server generating a label to send to a printer, that is usually the right trade, because a barcode font on a rendering server is a portability problem and Barby's SVG output is a vector file that any print pipeline handles.

The second comparison is against a barcode generation API on someone else's server. The difference in approach is that a hosted service is one line of code and no dependencies, and it is a network call per barcode with your data leaving your infrastructure and a third party deciding the format.

Barby's case is the same one it makes for the symbology and outputter split: the two things you are likely to need to customise, the symbology and the output format, are the two things Barby separates. A hosted service gives you one combination. Barby gives you thirteen symbologies and seven outputters that compose.

The honest limit is that a hosted service may support symbologies Barby does not, and Barby may be the wrong choice if you need a very specific symbology set that only exists as a service. For the common cases, a retail barcode, a shipping label, a QR code for a URL, the library covers them and keeps the data on your own infrastructure.

Editorial conclusion

Adopt Barby when you need to generate barcodes in Ruby and want the symbology and the output format chosen independently, so that adding a new format does not mean touching the encoding code. Do not adopt it if you need a symbology it does not implement, since the list is fixed at thirteen and QR Code, DataMatrix and PDF417 each pull in a native dependency. Verify first that your required symbology is in the table, that the dependency it needs is acceptable in your environment, PDF417 in particular requires JRuby, and that you require the symbology explicitly, because the library no longer loads them automatically.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. toretore/barby on GitHub