--- name: "shards" section: "1" platform: "linux" package: "shards" version: "0.19.1-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/shards" --- # shards(1) dependency manager for the Crystal Language ## NAME shards - dependency manager for the Crystal Language ## SYNOPSIS **shards** \[*\*...\] \[*\*\] \[*\*...\] ## DESCRIPTION Manages dependencies for Crystal projects and libraries with reproducible installs across computers and systems. ## USAGE *shards* requires the presence of a *shard.yml* file in the project folder (working directory). This file describes the project and lists dependencies that are required to build it. See [**shard.yml**(5)](/shard.yml/5.md) for more information on its format. A default file can be created by running *shards init*. Running *shards install* resolves and installs the specified dependencies. The installed versions are written into a **shard.lock** file for using the exact same dependency versions when running *shards install* again. If your shard builds an application, both **shard.yml** and **shard.lock** should be checked into version control to provide reproducible dependency installs. If it is only a library for other shards to depend on, **shard.lock** should *not* be checked in, only **shard.yml**. It’s good advice to add it to **.gitignore**. ## COMMANDS If no *command* is given, **install** command will be run by default. To see the available options for a particular command, use *--help* after the command. **build** \[*\*\] \[*\*...\] Builds the specified *\* in **bin** path. If no targets are specified, all are built. This command ensures all dependencies are installed, so it is not necessary to run **shards install** before. All *\* following the command are delegated to **crystal build**. **check** Verifies that all dependencies are installed and requirements are satisfied. Exit status: **0** Dependencies are satisfied. **1** Dependencies are not satisfied. **init** Initializes a default *shard.yml* in the current folder. **install** \[--frozen\] \[--without-development\] \[--production\] \[--skip-postinstall\] \[--skip-executables\] \[--jobs=N\] Resolves and installs dependencies into the *lib* folder. If not already present, generates a *shard.lock* file from resolved dependencies, locking version numbers or Git commits. Reads and enforces locked versions and commits if a *shard.lock* file is present. The **install** command may fail if a locked version doesn’t match a requirement, but may succeed if a new dependency was added, as long as it doesn’t generate a conflict, thus generating a new *shard.lock* file. - \--frozen Strictly installs locked versions from *shard.lock*. Fails if *shard.lock* is missing. - \--without-development Does not install development dependencies. - \--production same as *--frozen* and *--without-development* - \--skip-postinstall Does not run postinstall of dependencies. - \--skip-executables Does not install executables. - \--jobs Number of repository downloads to perform in parallel (default: 8). Currently only for git. **list** \[--tree\] Lists the installed dependencies and their versions. Specifying *--tree* arranges nested dependencies in a tree, instead of a flattened list. **lock** \[--update \[\...\]\] Resolves dependencies and creates or updates the *shard.lock* file as per the **install** command, but never installs the dependencies. Specifying *--update* follows the same semantics as the **update** command. **outdated** \[--pre\] Lists dependencies that are outdated. When *--pre* is specified, pre-release versions are also considered. **prune** Removes unused dependencies from *lib* folder. **update** \[\...\] Resolves and updates all dependencies into the *lib* folder, whatever the locked versions in the *shard.lock* file. Eventually generates a new *shard.lock* file. Specifying *shards* will update these dependencies only, trying to be as conservative as possible with other dependencies, respecting the locked versions in the *shard.lock* file. **version** \[*\*\] Prints the current version of the shard located at *path* (defaults to current directory). To see the available options for a particular command, use **--help** after a command. ## GENERAL OPTIONS - \--version Prints the version of *shards*. - \-h, --help Prints usage synopsis. - \--no-color Disables colored output. - \--local Do not update remote repository cache. Instead, Shards will use the local copies already present in the cache (see **SHARDS\_CACHE\_PATH**). The command will fail if a dependency is unavailable in the cache. - \-q, --quiet Decreases the log verbosity, printing only warnings and errors. - \-v, --verbose Increases the log verbosity, printing all debug statements. ## INSTALLATION Shards is usually distributed with Crystal itself. Alternatively, a separate *shards* package may be available for your system. To install from source, download or clone *the repository* \ and run **make CRFLAGS=--release**. The compiled binary is in *bin/shards* and should be added to **PATH**. ## ENVIRONMENT VARIABLES SHARDS\_OPTS Allows general options to be passed in as environment variable. **Example**: *SHARDS\_OPTS="--no-color" shards update* SHARDS\_CACHE\_PATH Defines the cache location. In this folder, shards stores local copies of remote repositories. Defaults to *.cache/shards* in the home directory (*$XDG\_CACHE\_HOME* or *$HOME*) or the current directory. SHARDS\_INSTALL\_PATH Defines the location where dependencies are installed. Defaults to *lib*. SHARDS\_BIN\_PATH Defines the location where executables are installed. Defaults to *bin*. CRYSTAL\_VERSION Defines the crystal version that dependencies should be resolved against. Defaults to the output of *crystal env CRYSTAL\_VERSION*. SHARDS\_OVERRIDE Defines an alternate location of *shard.override.yml*. ## FILES shard.yml Describes a shard project including its dependencies. See [**shard.yml**(5)](/shard.yml/5.md) for documentation. shard.override.yml Allows overriding the source and restriction of dependencies. An alternative location can be configured with the env var **SHARDS\_OVERRIDE**. The file contains a YAML document with a single **dependencies** key. It has the same semantics as in **shard.yml**. Dependency configuration takes precedence over the configuration in **shard.yml** or any dependency’s **shard.yml**. Use cases are local working copies, forcing a specific dependency version despite mismatching constraints, fixing a dependency, checking compatibility with unreleased dependency versions. shard.lock Lockfile that stores information about the installed versions. If your shard builds an application, **shard.lock** should be checked into version control to provide reproducible dependency installs. If it is only a library for other shards to depend on, **shard.lock** should *not* be checked in, only **shard.yml**. It’s good advice to add it to **.gitignore**. ## REPORTING BUGS Report shards bugs to \ Crystal Language home page: \ ## COPYRIGHT Copyright © 2025 Julien Portalier. *License Apache 2.0* \ This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. ## AUTHORS Written by Julien Portalier and the Crystal project. ## SEE ALSO [**shard.yml**(5)](/shard.yml/5.md)