Lucky Logo

# MacOS requirements

# 1. Install Homebrew

Installation instructions from the Homebrew website

/bin/bash -c "$(curl -fsSL"

# 2. Install OpenSSL

brew install openssl

# 3. Configure SSL for Crystal

You’ll need to add export PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig to your ~/.bash_profile or ~/.zshrc so Crystal can use SSL through the openssl package.

# For Bash, the default shell on MacOS
echo 'export PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig' >>~/.bash_profile

# For ZSH
echo 'export PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig' >>~/.zshrc

If you get an error like this: “Package libssl/libcrypto was not found in the pkg-config search path” then be sure to run this step so that Crystal knows where OpenSSL is located.

# Linux requirements

# Debian (Ubuntu should be similar)

apt-get install libc6-dev libevent-dev libpcre2-dev libpng-dev libssl1.0-dev libyaml-dev zlib1g-dev

# Fedora (28)

dnf install glibc-devel libevent-devel pcre2-devel openssl-devel libyaml-devel zlib-devel libpng-devel

# Crystal v0.33.0

# 1. Install Crystal

We recommend using a version manager to make sure the correct version of Crystal is used with Lucky. Try crenv (recommended) or asdf-crystal (great if you already use asdf)

Alternatively you could install Crystal without a version manager.

# 2. Check installation

crystal -v

Should return at least 0.33.0

# Install Lucky CLI on macOS

Once the required dependencies above are installed, set up Lucky for your system.

# 1. Add the Lucky tap to Homebrew

brew tap luckyframework/homebrew-lucky

# 2. Install the Lucky CLI with Homebrew

brew install lucky

# 3. Check installation

Let’s make sure the Lucky CLI installed correctly:

lucky -v

This should return 0.19.0

# Install Lucky CLI on Linux

# 1. Clone the CLI repo

git clone

# 2. Change into the newly cloned directory

cd lucky_cli

# 3. Check out the latest released version

git checkout v0.19.0

# 4. Install shards

We call packages/libraries in Crystal “shards”. Let’s install the shards that Lucky CLI needs:

shards install

# 5. Build the CLI

crystal build src/

# 6. Move the generated binary to your path

This will let you use lucky from the command line.

mv lucky /usr/local/bin

# 7. Check installation

Let’s make sure the Lucky CLI installed correctly:

lucky -v

This should return 0.19.0

# Process manager

Lucky uses a process manager to watch assets and start the server in development.

Install one of these process managers: Overmind (recommended), Heroku CLI (great if you plan to use Heroku to deploy), forego, or foreman.

By default Lucky creates a that defines what processes should be started when running lucky dev. You can modify the to start other processes like running background jobs.

# Postgres database

# 1. Install Postgres

Lucky uses Postgres for its database. Install Postgres (macOS/Others)

# 1a. (macOS only) Ensure Postgres CLI tools installed

If you’re using on macOS make sure Postgres CLI tools are installed

sudo mkdir -p /etc/paths.d &&
  echo /Applications/ | sudo tee /etc/paths.d/postgresapp

There are other installation methods available in Postgres CLI tools docs

# 2. Ensure Postgres CLI tools installed

psql --version

Should return psql (PostgreSQL) 10.x or higher.

# Chromedriver (optional)

You can skip this if you only plan to only build APIs.

If you want to test your frontend using LuckyFlow you will need Chromedriver, see the Testing HTML and Interactivity guide for details and installation.

# Node and Yarn (optional)

You can skip this if you only plan to only build APIs.

# 1. Install

# 2. Check installation

node -v
yarn -v

Node should return greater than v11. Yarn should return greater than 1.x.

See a problem? Have an idea for improvement? Edit this page on GitHub