Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

Installing Crystal and Your First Program

Install the Crystal compiler on Linux, macOS or Windows, then write, run and build your first program with crystal run and crystal build, including how to read compiler errors.

To run Crystal code you need the Crystal compiler, a program called crystal. It is free and open source. This lesson shows how to install it, create your first file, run it two different ways, and understand what the compiler tells you when something is wrong.

Crystal cannot run in the browser on this site, so the Crystal listings here are read-only. The Ruby stand-ins are runnable and show the same ideas. Everything below is exactly what you would type on your own computer.

Installing

The official install guide on the Crystal website always has the newest instructions, so treat the commands below as the common routes rather than something to memorise.

  • macOS: with Homebrew, run brew install crystal.
  • Linux: most distributions package it, or you can use the official repository for your distribution. A tarball for 64-bit Linux is also published for each release.
  • Windows: Crystal supports Windows natively; you can download the official installer or archive. Many Windows users also use WSL (Windows Subsystem for Linux) and install the Linux version, which behaves the same as on any Linux box.
  • Containers: the official crystallang/crystal Docker image has the compiler preinstalled, which is a quick way to try it without changing your machine.

After installing, open a terminal and check it works:

Terminal
crystal --version

You will see a version number, the LLVM version the compiler uses, and the default target. If the command is not found, the install folder is not on your PATH.

Your first file

Make a folder and create a file called hello.cr. Crystal source files use the extension .cr.

CRYSTAL
puts "Hello from Crystal!"

puts prints a value followed by a newline. Nothing else is needed: Crystal executes top-level code from the first line to the last.

Running it: crystal run

Terminal
crystal run hello.cr

This compiles the file to a temporary executable and runs it at once. It is the Crystal equivalent of ruby hello.rb. Because the compiler caches work, repeated runs of a small program feel quick. Shortcut: crystal hello.cr does the same thing.

The program prints:

TEXT
Hello from Crystal!

The runnable stand-in below is Ruby, where the same line is a complete program:

Ruby Stand-in: hello in Ruby

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Building an executable: crystal build

crystal run is for development. To get a real file you can copy to a server or give to someone, build it:

Terminal
crystal build hello.cr
./hello

This creates an executable called hello (hello.exe on Windows) next to the source. You can run it without Crystal installed on the target machine, as long as the system libraries it links to are available.

There are two kinds of build, and the difference matters:

Command What it does When to use it
crystal build hello.cr Fast to compile, little optimisation While developing
crystal build --release hello.cr Slow to compile, fully optimised For deployment and benchmarks

Never judge Crystal's speed from a build that was made without --release.

Reading the first program line by line

A slightly bigger program shows more of the language:

CRYSTAL
name = "Crystal"
year = 2014

puts "#{name} started in #{year}."
puts "That was #{2026 - year} years ago."
  • name = "Crystal" creates a variable. Its type, String, is inferred.
  • "#{...}" is string interpolation: any expression inside is converted to text and inserted.
  • 2026 - year is plain integer arithmetic.

The output is:

TEXT
Crystal started in 2014.
That was 12 years ago.

The Ruby stand-in runs the same idea. Note how similar it is:

Ruby Stand-in: interpolation in Ruby

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Your first compiler error

The compiler is strict, and it is your friend. Suppose you misspell a method name:

CRYSTAL
puts "abc".uppercase

The build fails before anything runs, with a message that looks like this (wording changes between versions):

TEXT
Error: undefined method 'uppercase' for String
Did you mean 'upcase'?

The compiler points at the file, the line and the column, and often suggests the right name. Ruby would also fail here, but only when that line executes. In a program with hundreds of rarely used branches, Crystal finds the problem on day one.

Common first-day errors:

  1. Missing end. Crystal blocks, methods and classes close with end, as in Ruby.
  2. Using a variable before assigning it. The compiler says it is undefined.
  3. Calling a method that can return nil without checking. You will meet this in union types.

Running code from standard input

For quick experiments you can pipe code into the compiler or use an interactive session. The official toolchain includes crystal eval for a one-liner:

Terminal
crystal eval 'puts 6 * 7'

This prints 42. There was historically an experimental interactive shell, but day-to-day work uses files and crystal run, so build the habit of saving small experiments as files.

An editor setup

Any text editor works. For a good experience install a Crystal extension for your editor (VS Code and the JetBrains IDEs both have Crystal support) and the Crystal Language Server, which gives completion and shows errors as you type. The built-in formatter (covered in the toolchain lesson) keeps your code tidy.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What file extension do Crystal source files use?

    Crystal source files end in .cr.
  2. 2. Which command compiles and runs a program in one step?

    crystal run compiles to a temporary executable and runs it. crystal build only produces the file.
  3. 3. Which flag should you use when building a program for deployment or for speed tests?

    --release turns on full optimisation. Plain builds are quicker to compile but slower to run.
  4. 4. When does Crystal report a misspelled method name like uppercase?

    The compiler checks the whole program, so an undefined method is a build error.

Summary

  • Install the crystal compiler with your package manager, an installer or Docker, then check with crystal --version.
  • Source files end in .cr; top-level code runs from top to bottom with no main needed.
  • crystal run file.cr compiles and runs; crystal build file.cr makes an executable.
  • Use --release for fast executables; skip it while developing.
  • Compiler errors arrive before the program runs and usually name the line and suggest fixes.

Next: The Compiler and Toolchain: Format, Spec, Docs