Installation

English · 简体中文 · 繁體中文 · Español · العربية · Français · Português (Brasil) · Deutsch · हिन्दी · 日本語 · 한국어 · Русский · Bahasa Indonesia · Türkçe · Italiano · Tiếng Việt

Installing docxi: requirements, Bundler setup and upgrading

docxi is a pure-Ruby gem. Installing it pulls in two dependencies, nokogiri and rubyzip, and nothing else. No office software is needed.

Requirements

Requirement	Version
Ruby	2.5 or newer
nokogiri	>= 1.8, < 2, installed automatically
rubyzip	>= 1.3, < 4, installed automatically
Rails	Not required

Install with Bundler

Add the gem to your Gemfile:

gem "docxi", "~> 0.1"

Then install it:

bundle install

Install without Bundler

gem install docxi

Check the installation

ruby -e 'require "docxi"; puts Docxi::VERSION'

In a Bundler project, run it as bundle exec ruby -e 'require "docxi"; puts Docxi::VERSION'. It prints the installed version, for example 0.1.0.

Upgrading from 0.0.x

If your Gemfile pins docxi to 0.0.x, for example with "~> 0.0.6", change the line to gem "docxi", "~> 0.1". Then run bundle update docxi. No code changes are needed, and 0.1.0 generates the same documents as 0.0.6: the test suite compares the output against files generated by 0.0.6.

What changed under the hood:

• nokogiri and rubyzip can now be any version from the ranges above, so docxi installs next to current Rails versions.
• docxi no longer needs ActiveSupport to be loaded.
• Archives are written without Zip64 records.
• Images are loaded without Kernel#open, so URLs work on Ruby 3.
• tab, frame and header page numbers work.

Apps running a Ruby older than 2.5 keep getting 0.0.6, because 0.1.0 declares Ruby 2.5 as its minimum. The Changelog lists every change.

Versions tested in CI

Each Rails version runs with the full framework loaded alongside docxi.

Ruby	Rails
2.5	5.2
2.7	6.0
3.0	6.1
3.1	7.0
3.2	7.1
3.3	7.2
3.4	8.0
4.0	8.1

CI also runs:

• the tests without Rails on Ruby 2.5, 2.6 and 4.0
• with rubyzip 1.3 (Ruby 2.5), rubyzip 2.4 (Ruby 3.3) and nokogiri 1.11 (Ruby 2.5)
• a check that LibreOffice can convert the sample documents

Platform notes

• nokogiri ships precompiled gems for common Linux, macOS and Windows platforms. Where none matches, it compiles from source and needs a C compiler. See the nokogiri installation guide.
• CI runs on Ubuntu 24.04, and the tests have also been run on macOS. Windows isn't tested.

If installation fails

Bundler conflicts on nokogiri or rubyzip almost always mean an old docxi 0.0.6 is being resolved. See Troubleshooting.

Related pages

• Getting Started
• Configuration
• Deployment

---

← Wiki home · README