Skip to content
Offical Rubyzip repository
Ruby Makefile
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib Merge pull request #418 from hainesr/open-options Oct 19, 2019
samples Turn off all terminal output in all tests. Apr 4, 2018
test Update tests to check error messages. Oct 13, 2019
.gitignore Fixing Zip#read_local_entry error on JRuby Mar 7, 2015
.rubocop_rubyzip.yml Revert "fix rubocop cop Style/ClassCheck". It cause regression in tests Jun 8, 2015
.simplecov Fix warning: `::[] is deprecated. Use ::new instead.` Jan 8, 2017
.travis.yml Drop old ruby and JDK versions from CI Sep 18, 2019 Update changelog for #416 and #418 Oct 19, 2019
Gemfile Move dependencies to the gemspec and lock down versions. Jul 23, 2014
Guardfile use guard for testing Jan 5, 2015 Bump version to 2.0.0 Sep 25, 2019
Rakefile fix rubocop Style/HashSyntax cop Mar 24, 2015
TODO Fix for #126 and #127 Jan 24, 2014
rubyzip.gemspec Merge pull request #406 from rubyzip/bump-supported-ruby Sep 25, 2019


Gem Version Build Status Code Climate Coverage Status

Rubyzip is a ruby library for reading and writing zip files.

Important note

The Rubyzip interface has changed!!! No need to do require "zip/zip" and Zip prefix in class names removed.

If you have issues with any third-party gems that require an old version of rubyzip, you can use this workaround:

gem 'rubyzip', '>= 1.0.0' # will load new rubyzip version
gem 'zip-zip' # will load compatibility for old rubyzip API.


  • Ruby 2.4 or greater (for rubyzip 2.0; use 1.x for older rubies)


Rubyzip is available on RubyGems:

gem install rubyzip

Or in your Gemfile:

gem 'rubyzip'


Basic zip archive creation

require 'rubygems'
require 'zip'

folder = "Users/me/Desktop/stuff_to_zip"
input_filenames = ['image.jpg', 'description.txt', 'stats.csv']

zipfile_name = "/Users/me/Desktop/", Zip::File::CREATE) do |zipfile|
  input_filenames.each do |filename|
    # Two arguments:
    # - The name of the file as it will appear in the archive
    # - The original file, including the path to find it
    zipfile.add(filename, File.join(folder, filename))
  zipfile.get_output_stream("myFile") { |f| f.write "myFile contains just this" }

Zipping a directory recursively

Copy from here

require 'zip'

# This is a simple example which uses rubyzip to
# recursively generate a zip file from the contents of
# a specified directory. The directory itself is not
# included in the archive, rather just its contents.
# Usage:
#   directory_to_zip = "/tmp/input"
#   output_file = "/tmp/"
#   zf =, output_file)
#   zf.write()
class ZipFileGenerator
  # Initialize with the directory to zip and the location of the output archive.
  def initialize(input_dir, output_file)
    @input_dir = input_dir
    @output_file = output_file

  # Zip the input directory.
  def write
    entries = Dir.entries(@input_dir) - %w[. ..], ::Zip::File::CREATE) do |zipfile|
      write_entries entries, '', zipfile


  # A helper method to make the recursion work.
  def write_entries(entries, path, zipfile)
    entries.each do |e|
      zipfile_path = path == '' ? e : File.join(path, e)
      disk_file_path = File.join(@input_dir, zipfile_path)

      if disk_file_path
        recursively_deflate_directory(disk_file_path, zipfile, zipfile_path)
        put_into_archive(disk_file_path, zipfile, zipfile_path)

  def recursively_deflate_directory(disk_file_path, zipfile, zipfile_path)
    zipfile.mkdir zipfile_path
    subdir = Dir.entries(disk_file_path) - %w[. ..]
    write_entries subdir, zipfile_path, zipfile

  def put_into_archive(disk_file_path, zipfile, zipfile_path)
    zipfile.add(zipfile_path, disk_file_path)

Save zip archive entries in sorted by name state

To save zip archives in sorted order like below, you need to set ::Zip.sort_entries to true


After this, entries in the zip archive will be saved in ordered state.

Default permissions of zip archives

On Posix file systems the default file permissions applied to a new archive are (0666 - umask), which mimics the behavior of standard tools such as touch.

On Windows the default file permissions are set to 0644 as suggested by the Ruby File documentation.

When modifying a zip archive the file permissions of the archive are preserved.

Reading a Zip file

MAX_SIZE = 1024**2 # 1MiB (but of course you can increase this)'') do |zip_file|
  # Handle entries one by one
  zip_file.each do |entry|
    puts "Extracting #{}"
    raise 'File too large when extracted' if entry.size > MAX_SIZE

    # Extract to file or directory based on name in the archive

    # Read into memory
    content =

  # Find specific entry
  entry = zip_file.glob('*.csv').first
  raise 'File too large when extracted' if entry.size > MAX_SIZE

Notice about ::Zip::InputStream

::Zip::InputStream usable for fast reading zip file content because it not read Central directory.

But there is one exception when it is not working - General Purpose Flag Bit 3.

If bit 3 (0x08) of the general-purpose flags field is set, then the CRC-32 and file sizes are not known when the header is written. The fields in the local header are filled with zero, and the CRC-32 and size are appended in a 12-byte structure (optionally preceded by a 4-byte signature) immediately after the compressed data

If ::Zip::InputStream finds such entry in the zip archive it will raise an exception.

Password Protection (Experimental)

Rubyzip supports reading/writing zip files with traditional zip encryption (a.k.a. "ZipCrypto"). AES encryption is not yet supported. It can be used with buffer streams, e.g.:

Zip::OutputStream.write_buffer(''),'password')) do |out|
  out.write my_data

This is an experimental feature and the interface for encryption may change in future versions.

Known issues

Modify docx file with rubyzip

Use write_buffer instead open. Thanks to @jondruse

buffer = Zip::OutputStream.write_buffer do |out|
  @zip_file.entries.each do |e|
    unless [DOCUMENT_FILE_PATH, RELS_FILE_PATH].include?(

  out.write xml_doc.to_xml(:indent => 0).gsub("\n","")

  out.write rels.to_xml(:indent => 0).gsub("\n","")
end, "wb") {|f| f.write(buffer.string) }


Existing Files

By default, rubyzip will not overwrite files if they already exist inside of the extracted path. To change this behavior, you may specify a configuration option like so:

Zip.on_exists_proc = true

If you're using rubyzip with rails, consider placing this snippet of code in an initializer file such as config/initializers/rubyzip.rb

Additionally, if you want to configure rubyzip to overwrite existing files while creating a .zip file, you can do so with the following:

Zip.continue_on_exists_proc = true

Non-ASCII Names

If you want to store non-english names and want to open them on Windows(pre 7) you need to set this option:

Zip.unicode_names = true

Sometimes file names inside zip contain non-ASCII characters. If you can assume which encoding was used for such names and want to be able to find such entries using find_entry then you can force assumed encoding like so:

Zip.force_entry_names_encoding = 'UTF-8'

Allowed encoding names are the same as accepted by String#force_encoding

Date Validation

Some zip files might have an invalid date format, which will raise a warning. You can hide this warning with the following setting:

Zip.warn_invalid_date = false

Size Validation

By default (in rubyzip >= 2.0), rubyzip's extract method checks that an entry's reported uncompressed size is not (significantly) smaller than its actual size. This is to help you protect your application against zip bombs. Before extracting an entry, you should check that its size is in the range you expect. For example, if your application supports processing up to 100 files at once, each up to 10MiB, your zip extraction code might look like:

MAX_FILE_SIZE = 10 * 1024**2 # 10MiB
MAX_FILES = 100'') do |zip_file|
  num_files = 0
  zip_file.each do |entry|
    num_files += 1 if entry.file?
    raise 'Too many extracted files' if num_files > MAX_FILES
    raise 'File too large when extracted' if entry.size > MAX_FILE_SIZE

If you need to extract zip files that report incorrect uncompressed sizes and you really trust them not too be too large, you can disable this setting with

Zip.validate_entry_sizes = false

Note that if you use the lower level Zip::InputStream interface, rubyzip does not check the entry sizes. In this case, the caller is responsible for making sure it does not read more data than expected from the input stream.

Default Compression

You can set the default compression level like so:

Zip.default_compression = Zlib::DEFAULT_COMPRESSION


Zip64 Support

By default, Zip64 support is disabled for writing. To enable it do this:

Zip.write_zip64_support = true

NOTE: If you will enable Zip64 writing then you will need zip extractor with Zip64 support to extract archive.

Block Form

You can set multiple settings at the same time by using a block:

  Zip.setup do |c|
    c.on_exists_proc = true
    c.continue_on_exists_proc = true
    c.unicode_names = true
    c.default_compression = Zlib::BEST_COMPRESSION


To run the test you need to do this:

bundle install

Website and Project Home


Alexander Simonov ( alex at

Alan Harper ( alan at

Thomas Sondergaard (thomas at

Technorama Ltd. (oss-ruby-zip at

extra-field support contributed by Tatsuki Sugiura (sugi at


Rubyzip is distributed under the same license as ruby. See

You can’t perform that action at this time.