class Axlsx::Package

Package is responsible for managing all the bits and peices that Open Office XML requires to make a valid xlsx document including valdation and serialization.

Initializes your package

Examples: :author => 'you!', :workbook =>


  • options (Hash) (defaults to: {})

    A hash that you can use to specify the author and workbook for this package.

Options Hash (options):

  • :author (String)

    The author of the document

  • :created_at (Time)

    Timestamp in the document properties (defaults to current time).

  • :use_shared_strings (Boolean)

    This is passed to the workbook to specify that shared strings should be used when serializing the package.


  • (_self)

Yield Parameters:

  • _self (Axlsx::Package)

    the object that the method was called on

provides access to the app doc properties for this package see App

Creates the minimum content types for generating a valid xlsx document.

Appends override objects for drawings, charts, and sheets as they exist in your workbook to the default content types.

provides access to the core doc properties for the package see Core

Encrypt the package into a CFB using the password provided This is not ready yet

The parts of a package

Creates the relationships required for a valid xlsx document


A tremendous amount of effort has gone into ensuring that you cannot create invalid xlsx documents. confirm_valid should be used in the rare case that you cannot open the serialized file.

Serialize your workbook to disk as an xlsx document.


# This is how easy it is to create a valid xlsx file. Of course you might want to add a sheet or two, and maybe some data, styles and charts.
# Take a look at the README for an example of how to do it!

#serialize to a file
p =
# ......add cool stuff to your workbook......

# Serialize to a stream
s = p.to_stream()'example_streamed.xlsx', 'w') { |f| f.write( }


  • output (String)

    The name of the file you want to serialize your package to

  • confirm_valid (Boolean) (defaults to: false)

    Validate the package prior to serialization.

Serialize your workbook to a StringIO instance


  • confirm_valid (Boolean) (defaults to: false)

    Validate the package prior to serialization.

Shortcut to specify that the workbook should use autowidth

Shortcut to determine if the workbook is configured to use shared strings

Shortcut to specify that the workbook should use shared strings


This gem includes all schema from and as per ECMA-376, Third edition. opc schema require an internet connection to import remote schema from dublin core for dc, dcterms and xml namespaces. Those remote schema are included in this gem, and the original files have been altered to refer to the local versions.

If by chance you are able to creat a package that does not validate it indicates that the internal validation is not robust enough and needs to be improved. Please report your errors to the gem author.

Validate all parts of the package against xsd schema.


# The following will output any error messages found in serialization.
p =
# ... code to create sheets, charts, styles etc.
p.validate.each { |error| puts error.message }

Performs xsd validation for a signle document


  • schema (String)

    path to the xsd schema to be used in validation.

  • doc (String)

    The xml text to be validated


As there are multiple ways to instantiate a workbook for the package, here are a few examples:

# assign directly during package instanciation
wb = =>

# get a fresh workbook automatically from the package
wb =
#     # set the workbook after creating the package
wb = =

The workbook this package will serialize or validate.


  • (@workbook)


  • ArgumentError if workbook parameter is not a Workbook instance.

Writes the package parts to a zip archive.


  • zip (Zip::OutputStream)

Generate a Entry for the given package part. The important part here is to explicitly set the timestamp for the zip entry: Serializing axlsx packages with identical contents should result in identical zip files – however, the timestamp of a zip entry defaults to the time of serialization and therefore the zip file contents would be different every time the package is serialized.

Note: Core#created also defaults to the current time – so to generate identical axlsx packages you have to set this explicitly, too (eg. with ` Time.local(2013, 1, 1))`).


  • part

    A hash describing a part of this pacakge (see #parts)

Package is referenced in 0 repositories