Skip to content
Easily create & extract archives, and compress & decompress files of various formats
Go Shell
Branch: master
Clone or download
nmiyake and mholt Add CI check to ensure module definition is correct (#198)
* Add CI check to ensure module definition is correct

Fail verification if "go mod tidy" results in any modifications
to go.mod or go.sum.

* Improve pipeline

* Use script

* Add working directory

* Fix module definition script for Windows

* Add git configuration for autocrlf

* Simplify

* Revert "Simplify"

This reverts commit b7d8b0f.

* Flip core.autocrlf

* Add .gitattributes to prevent line ending conversion

* Try approach without .gitattributes

* Add checkout step
Latest commit 44285f7 Nov 29, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Create FUNDING.yml Oct 30, 2019
cmd/arc Fix module name (#190) Nov 14, 2019
testdata Merge branch 'fix-hardlinks' Nov 22, 2019
.gitignore refactor (#11) Oct 10, 2016
LICENSE Initial commit Apr 8, 2016 Use latest compress lib and update readme Nov 14, 2019
archiver.go Update DecompressFile docs (#177) Aug 12, 2019
archiver_test.go Oops, add brotli to archive formats list Jun 23, 2019
azure-pipelines.yml Add CI check to ensure module definition is correct (#198) Nov 29, 2019
brotli.go Add brotli (closes #161) Jun 23, 2019
build.bash build.bash: Remove BSD and 32-bit, arm64 Linux builds Dec 5, 2018
bz2.go Convenience functions for matching formats, and constructor functions Nov 18, 2018
doc_test.go Implement Walk and Extract package funcs and add examples to docs Dec 3, 2018
filecompressor.go Convenience functions for matching formats, and constructor functions Nov 18, 2018
filecompressor_test.go Convenience functions for matching formats, and constructor functions Nov 18, 2018
go.mod go.mod: update to v1.0.0 (#193) Nov 14, 2019
go.sum go.mod: update to v1.0.0 (#193) Nov 14, 2019
gz.go gzip: Default to parallel gzip by klauspost (#159) Jun 23, 2019
lz4.go go.mod: Update to module version (#192) Nov 14, 2019
rar.go rar: Fixed directory extracting (#135) Jan 14, 2019
sz.go Convenience functions for matching formats, and constructor functions Nov 18, 2018
tar.go Merge branch 'fix-hardlinks' Nov 22, 2019
tar_test.go Fix import path in test (#197) Nov 25, 2019
tarbrotli.go brotli: Fix panic for files Jun 23, 2019
tarbz2.go Convenience functions for matching formats, and constructor functions Nov 18, 2018
targz.go gzip: Default to parallel gzip by klauspost (#159) Jun 23, 2019
tarlz4.go go.mod: Update to module version (#192) Nov 14, 2019
tarsz.go Convenience functions for matching formats, and constructor functions Nov 18, 2018
tarxz.go Convenience functions for matching formats, and constructor functions Nov 18, 2018
tarzst.go Finish implementing zstd: tar.zstd and command usage Jun 11, 2019
xz.go Convenience functions for matching formats, and constructor functions Nov 18, 2018
zip.go Keep permissions on unzipped folders (#134) Jan 9, 2019
zstd.go Add Zstandard format (closes #170) Jun 11, 2019

archiver archiver GoDoc

Introducing Archiver 3.1 - a cross-platform, multi-format archive utility and Go library. A powerful and flexible library meets an elegant CLI in this generic replacement for several platform-specific or format-specific archive utilities.


Package archiver makes it trivially easy to make and extract common archive formats such as tarball (and its compressed variants) and zip. Simply name the input and output file(s). The arc command runs the same on all platforms and has no external dependencies (not even libc). It is powered by the Go standard library and several third-party, pure-Go libraries.

Files are put into the root of the archive; directories are recursively added, preserving structure.

  • Make whole archives from a list of files
  • Open whole archives to a folder
  • Extract specific files/folders from archives
  • Stream files in and out of archives without needing actual files on disk
  • Traverse archive contents without loading them
  • Compress files
  • Decompress files
  • Streaming compression and decompression
  • Several archive and compression formats supported

Format-dependent features

  • Gzip is multithreaded
  • Optionally create a top-level folder to avoid littering a directory or archive root with files
  • Toggle overwrite existing files
  • Adjust compression level
  • Zip: store (not compress) already-compressed files
  • Make all necessary directories
  • Open password-protected RAR archives
  • Optionally continue with other files after an error

Supported compression formats

  • brotli (br)
  • bzip2 (bz2)
  • flate (zip)
  • gzip (gz)
  • lz4
  • snappy (sz)
  • xz
  • zstandard (zstd)

Supported archive formats

  • .zip
  • .tar (including any compressed variants like .tar.gz)
  • .rar (read-only)

Tar files can optionally be compressed using any of the above compression formats.


To install the runnable binary to your $GOPATH/bin:

$ go install

Or download binaries from the releases page.

To use as a dependency in your project:

$ go get

Command Use

Make new archive

# Syntax: arc archive [archive name] [input files...]

$ arc archive test.tar.gz file1.txt images/file2.jpg folder/subfolder

(At least one input file is required.)

Extract entire archive

# Syntax: arc unarchive [archive name] [destination]

$ arc unarchive test.tar.gz

(The destination path is optional; default is current directory.)

The archive name must end with a supported file extension—this is how it knows what kind of archive to make. Run arc help for more help.

List archive contents

# Syntax: arc ls [archive name]

$ arc ls caddy_dist.tar.gz
drwxr-xr-x  matt    staff   0       2018-09-19 15:47:18 -0600 MDT   dist/
-rw-r--r--  matt    staff   6148    2017-08-07 18:34:22 -0600 MDT   dist/.DS_Store
-rw-r--r--  matt    staff   22481   2018-09-19 15:47:18 -0600 MDT   dist/CHANGES.txt
-rw-r--r--  matt    staff   17189   2018-09-19 15:47:18 -0600 MDT   dist/EULA.txt
-rw-r--r--  matt    staff   25261   2016-03-07 16:32:00 -0700 MST   dist/LICENSES.txt
-rw-r--r--  matt    staff   1017    2018-09-19 15:47:18 -0600 MDT   dist/README.txt
-rw-r--r--  matt    staff   288     2016-03-21 11:52:38 -0600 MDT   dist/

Extract a specific file or folder from an archive

# Syntax: arc extract [archive name] [path in archive] [destination on disk]

$ arc extract test.tar.gz foo/hello.txt extracted/hello.txt

Compress a single file

# Syntax: arc compress [input file] [output file]

$ arc compress test.txt compressed_test.txt.gz
$ arc compress test.txt gz

For convenience, the output file (second argument) may simply be a compression format (without leading dot), in which case the output filename will be the same as the input filename but with the format extension appended, and the input file will be deleted if successful.

Decompress a single file

# Syntax: arc decompress [input file] [output file]

$ arc decompress test.txt.gz original_test.txt
$ arc decompress test.txt.gz

For convenience, the output file (second argument) may be omitted. In that case, the output filename will have the same name as the input filename, but with the compression extension stripped from the end; and the input file will be deleted if successful.


Flags are specified before the subcommand. Use arc help or arc -h to get usage help and a description of flags with their default values.

Library Use

The archiver package allows you to easily create and open archives, walk their contents, extract specific files, compress and decompress files, and even stream archives in and out using pure io.Reader and io.Writer interfaces, without ever needing to touch the disk.

import ""

See the package's GoDoc for full API documentation.

For example, creating or unpacking an archive file:

err := archiver.Archive([]string{"testdata", "other/file.txt"}, "")
// ...
err = archiver.Unarchive("test.tar.gz", "test")

The archive format is determined by file extension. (There are several functions in this package which perform a task by inferring the format from file extension or file header, including Archive(), Unarchive(), CompressFile(), and DecompressFile().)

To configure the archiver used or perform, create an instance of the format's type:

z := archiver.Zip{
	CompressionLevel:       flate.DefaultCompression,
	MkdirAll:               true,
	SelectiveCompression:   true,
	ContinueOnError:        false,
	OverwriteExisting:      false,
	ImplicitTopLevelFolder: false,

err := z.Archive([]string{"testdata", "other/file.txt"}, "/Users/matt/Desktop/")

Inspecting an archive:

err = z.Walk("/Users/matt/Desktop/", func(f archiver.File) error {
	zfh, ok := f.Header.(zip.FileHeader)
	if ok {
		fmt.Println("Filename:", zfh.Name)
	return nil

Streaming files into an archive that is being written to the HTTP response:

err = z.Create(responseWriter)
if err != nil {
	return err
defer z.Close()

for _, fname := range filenames {
	info, err := os.Stat(fname)
	if err != nil {
		return err
	// get file's name for the inside of the archive
	internalName, err := archiver.NameInArchive(info, fname, fname)
	if err != nil {
		return err

	// open the file
	file, err := os.Open(f)
	if err != nil {
		return err

	// write it to the archive
	err = z.Write(archiver.File{
		FileInfo: archiver.FileInfo{
			FileInfo:   info,
			CustomName: internalName,
		ReadCloser: file,
	if err != nil {
		return err

The archiver.File type allows you to use actual files with archives, or to mimic files when you only have streams.

There's a lot more that can be done, too. See the GoDoc for full API documentation.

Security note: This package does NOT attempt to mitigate zip-slip attacks. It is extremely difficult to do properly and seemingly impossible to mitigate effectively across platforms. Attempted fixes have broken processing of legitimate files in production, rendering the program unusable. Our recommendation instead is to inspect the contents of an untrusted archive before extracting it (this package provides Walkers) and decide if you want to proceed with extraction.

Project Values

This project has a few principle-based goals that guide its development:

  • Do our thing really well. Our thing is creating, opening, inspecting, compressing, and streaming archive files. It is not meant to be a replacement for specific archive format tools like tar, zip, etc. that have lots of features and customizability. (Some customizability is OK, but not to the extent that it becomes overly complicated or error-prone.)

  • Have good tests. Changes should be covered by tests.

  • Limit dependencies. Keep the package lightweight.

  • Pure Go. This means no cgo or other external/system dependencies. This package should be able to stand on its own and cross-compile easily to any platform -- and that includes its library dependencies.

  • Idiomatic Go. Keep interfaces small, variable names semantic, vet shows no errors, the linter is generally quiet, etc.

  • Be elegant. This package should be elegant to use and its code should be elegant when reading and testing. If it doesn't feel good, fix it up.

  • Well-documented. Use comments prudently; explain why non-obvious code is necessary (and use tests to enforce it). Keep the docs updated, and have examples where helpful.

  • Keep it efficient. This often means keep it simple. Fast code is valuable.

  • Consensus. Contributions should ideally be approved by multiple reviewers before being merged. Generally, avoid merging multi-chunk changes that do not go through at least one or two iterations/reviews. Except for trivial changes, PRs are seldom ready to merge right away.

  • Have fun contributing. Coding is awesome!

We welcome contributions and appreciate your efforts! However, please open issues to discuss any changes before spending the time preparing a pull request. This will save time, reduce frustration, and help coordinate the work. Thank you!

You can’t perform that action at this time.