shards v0.9.0

Dependency manager for the Crystal language


Dependency manager for the Crystal language.


Crystal applications and libraries are expected to have a shard.yml file at their root looking like this:

name: shards
version: 0.1.0

    github: datanoise/
    branch: master

    version: ~> 0.3.1

license: MIT

When libraries are installed from Git repositories, the repository is expected to have version tags following a semver-like format, prefixed with a v. Examples: v1.2.3, v2.0.0-rc1 or v2017.04.1.

Please see the SPEC for more details about the shard.yml format.


Shards is usually distributed with Crystal itself (e.g. Homebrew and Debian packages). Alternatively, a shards package may be available for your system.

You can download a source tarball from the same page (or clone the repository) then run make CRFLAGS=--releaseand copy bin/shards into your PATH. For example /usr/local/bin.

You are now ready to create a shard.yml for your projects (see details in SPEC). You can type shards init to have an example shard.yml file created for your project.

Run shards install to install your dependencies, which will lock your dependencies into a shard.lock file. You should check both shard.yml and shard.lock into version control, so further shards install will always install locked versions, achieving reproducible installations across computers.

Run shards --help to list other commands with their options.

Happy Hacking!


These requirements are only for compiling Shards.

  • Crystal

    Please refer to for instructions for your operating system.

  • libyaml

    On Debian/Ubuntu Linux you may install the libyaml-dev package.

    On Mac OS X you may install it using homebrew with brew install libyaml then make sure to have /usr/local/lib in your LIBRARY_PATH environment variable (eg: export LIBRARY_PATH="/usr/local/lib:$LIBRARY_PATH"). Please adjust the path per your Homebrew installation.


Licensed under the Apache License, Version 2.0. See LICENSE for details.


v0.9.0 - 2019-06-13


  • Allow resolving pre-release when installing git refs;
  • Report all available versions (Git resolver);
  • Don't prune everything in lib directory.

v0.9.0.rc2 - 2019-05-07


  • Exit with non-zero status on dependency resolve error;
  • Install dependency at HEAD when no version tags are defined;
  • Install executables using shard.yml at commit (not version).

v0.9.0.rc1 - 2019-01-11

Breaking changes:

  • Dependency solver was overhauled;
  • Git tag refs that match a version number are now an actual version (i.e. tag: v1.0.0 is converted to version: 1.0.0).


  • Update specified shards only, trying to keep other shards to their locked version if possible;
  • Add --local argument to use the cache as-is, allowing to skip git fetches when you know the cache is up-to-date;
  • Add the outdated command to list dependencies that could be updated (matching constraints) as well as their latest version; including pre-release versions on demand.
  • Add the lock command that behaves like the install and update commands but that only creates a lockfile, and doesn't install anything.


  • Transitive dependencies are now available to all installed shards, allowing postinstall scripts to compile any Crystal application;
  • Don't consider metadata when considering a pre-release version number.

v0.9.0.beta - 2019-01-11

Breaking changes:

  • A shard.yml spec is now required in libraries.
  • Drop support for obsolete Projectfile.


  • Experimental support for prereleases. Add a letter to a version number to declare a pre-release. For example 1.2.3.alpha or 1.0.0-rc1.
  • Ignore semver metadata (+abc).


  • Approximate operator used to match invalid version numbers (e.g. ~> 0.1.0 wrongly matched 0.10.0).
  • Unbalanced version numbers, such as 1.0.0 and are now correctly ordered and compared as > 1.0.0.
  • Force the 'v' prefix in version tags.
  • install -t isn't supported on macOS.

v0.8.1 - 2018-06-17


  • Git repositories cloned with v0.8.0 can't fetch new remote refs anymore, which totally broke the update command.
  • The Path resolver incorrectly handled invalid symlinks.

v0.8.0 - 2018-06-05 [REVOKED]


  • Install shard executables inside project bin folder on shard install. See #126.


  • Global cache for cloned Git repositories, aside crystal cache (e.g. ~/.cache/shards). Customizable with SHARDS_CACHE_PATH.
  • Clone bare Git repositories instead of creating mirrors (fetch should be faster, and less space required on disk).
  • Man pages are now in the man folder.
  • Allow loose shard versioning, accepting semver-like versions and alternatives such as calver.


  • Compatibility with Crystal 0.25.

v0.7.2 - 2017-11-16


  • Version command to print-out the project's version, see #147


  • Don't consider a Git refs to be a version number, see #169
  • Use installed spec for executing scripts, see #143
  • Don't expect shard.lock when shard.yml has no dependencies, see #145
  • Compatibility with Crystal 0.24.0 (unreleased)
  • Harmonize error messages
  • Correct shard.yml parse error line:column reporting

v0.7.1 - 2016-11-24


  • correctly updates or keeps dependencies, see #107, #141
  • upgrades minitest dependency so test do run

v0.7.0 - 2016-11-18


  • Build command for targets entry in SPEC
  • New Crystal search path algorithm (see breaking changes below)
  • Informational crystal entry in SPEC
  • Informational libraries entry in SPEC
  • Shorthand for dependencies

Breaking Changes:

  • Dependencies are installed in the lib directory
  • Dependencies are now fully installed, instead of merely the src folder
  • postinstall scripts are now executed from the root of the dependency, not the src directory


  • crash when dependency keys were unordered
  • tar command usage on OpenBSD
  • correctly report git errors
  • the update command created a lockfile for empty dependencies

v0.6.4 - 2016-11-18


  • Compatibility with Crystal 0.19.0

v0.6.3 - 2016-05-05


  • Compatibility with Crystal > 0.15.0
  • Relative paths for path dependencies, see #99

v0.6.2 - 2016-03-07


  • Don't crash when git binary is missing.

v0.6.1 - 2016-02-16


  • Compatibility with Crystal > 0.11.1

v0.6.0 - 2016-01-23


  • prune command to remove extraneous libs
  • init command to create an initial shard.yml


  • print details when postinstall script fails, see #84
  • path resolver didn't verify the path actually existed, see #77
  • recursion when shard name doesn't match dependency name, see #72

v0.5.4 - 2015-12-23


  • Compatibility with Crystal > 0.9.1

v0.5.3 - 2015-10-23


  • Git resolver didn't install the locked commit when using branch, tag or commit or just failed to install the dependency, see #65 and #67

v0.5.2 - 2015-10-02


  • compilation on Crystal 0.9.0

v0.5.1 - 2015-10-02


  • always generate a shard.yml when installing legacy dependencies, see #60
  • only create libs and .shards folders when required, see #61

v0.5.0 - 2015-09-28

Breaking Change:

  • renamed --no-colors option as --no-color to match crystal


  • nice error messages for invalid shard.yml files


  • upgraded to Crystal 0.8.0
  • custom YAML parser for shard.yml compliant to the spec
  • binary releases for OS X and Linux 32 bits


  • install command fails to install dependencies on fresh projects
  • check command breaks whenever a dependency is missing
  • manager doesn't resolve dependencies of development dependencies recursively
  • support for Git < 1.7.11 (eg: Ubuntu Precise and Debian Wheezy)
  • don't generate lockfile for projects without dependencies
  • don't fail when loading empty Projectfile

v0.4.0 - 2015-09-14


  • lock resolved versions for indempotent installs across computers, see #27
  • --production parameter to skip development dependencies
  • postintall hook to run a command after installing a dependency, see #19

Breaking Changes:

  • dropped support for custom dependency groups (but kept development_dependencies), see #27


  • compatibility with Crystal 0.7.7

v0.3.1 - 2015-08-16


  • don't install dependencies from optional groups recursively
  • manager didn't install path dependencies anymore

v0.3.0 - 2015-08-03


  • optional groups of dependencies, see #8
  • generates default shard.yml from Git tags and Projectfile dependencies, see #6


  • clone repository again when Git remote origin changes, see #4

v0.2.0 - 2015-06-03


  • correctly accesses git versioned shard.yml files;
  • correctly links/extracts the src folder as the libs/<name> folder for both Git and path resolvers.

v0.1.0 - 2015-05-23

Initial release.

Github statistic:
  • 573
  • 7
  • 62
  • 34
  • 35
  • 8 days ago