Crystal Releases

Crystal 1.20.0 is released!

2026-04-16T00:00:00+00:00

We are announcing a new Crystal release 1.20.0 with several new features and bug fixes.

Pre-built packages are available on GitHub Releases and our official distribution channels. See crystal-lang.org/install for installation instructions.

This release includes 161 changes since 1.19.1 by 21 contributors. We thank all the contributors for all the effort put into improving the language! ❤️

Below we list the most remarkable changes in the language, compiler and stdlib. For more details, visit the full changelog.

We do not expect any breaking changes in existing code. We expect the few bugfixes below to not negatively impact your programs. If you notice any unexpected issues, please let us know in the issue tracker or forum.

OpenSSL sockets shouldn’t flush on read (#16650)
Fix Process#wait to not close @input before waiting (#16620, #16638)
Ensure that heredoc lexing allows only valid identifiers (#16548)

Thanks @straight-shoota, @ysbaddaden, @Sija

HTTP::Server accepted requests containing both Content-Length and Transfer-Encoding headers and prioritized Content-Length. This allowed HTTP request smuggling as per CWE-444 when the server is behind a vulnerable frontend. Refer to the advisory for more details.

HTTP::Server now rejects requests where both headers are present. The HTTP parser now ignores Content-Length when the Transfer-Encoding header is present. (commit c948b31).

RFC 0020 introduces a new @[TargetFeature] annotation that allows specifying CPU features or a CPU model or variant for individual functions. It complements the --mattr and --mcpu CLI arguments that target the whole program. This allows embedding multiple optimized functions for different CPU features into a single executable, for example a portable SIMD implementation alongside AVX2 and AVX512 alternatives.

The program is responsible for detecting which feature is available and calling the proper function at runtime. Otherwise, the program might crash with SIGILL, for example.

For example:

{% if flag?(:x86_64) %}
  @[TargetFeature("+avx2")]
  private def foo_avx2
  end

  private def cpu_supports_avx2?
  end
{% end %}

private def foo_portable
end

def foo
  {% if flag?(:x86_64) %}
    return foo_avx2 if cpu_supports_avx2?
  {% end %}
  foo_portable
end

While not strictly required, we still recommend wrapping architecture-specific method definitions within macro flag checks.

Add @[TargetFeature] annotation (#16717)

Thanks @stakach

Execution contexts from RFC 0002 continue as a final preview feature, enabled with the compiler flags -Dpreview_mt -Dexecution_context. We plan to enable it by default in Crystal 1.21.

In addition to fixing bugs, we implemented M:N scheduling that allows threads to be attached to and detached from a context. This avoids blocking other fibers on certain syscalls, such as getaddrinfo.

Add Fiber::ExecutionContext::ThreadPool (#15885, #16750)
Detach execution context scheduler from running thread during blocking syscall (#15871, #16679)

The parallel contexts now automatically start threads to adapt to the actual workload and distribute fibers across more cores when needed.

Add adaptive scaling to ExecutionContext::Parallel (#16719)

This effort is part of the ongoing project to improve multi-threading support with the help of 84codes.

Thanks @ysbaddaden

This release brings a new ergonomic, safe, and portable API for spawning sub-processes, as proposed in RFC 0025.

A significant change is that the modern API treats the command line as an array of strings. The first element is the program to execute, and the remaining elements are its arguments.

# legacy API:
Process.run("crystal", ["tool", "format"])

# modern API:
Process.run(["crystal", "tool", "format"])

The new API also includes convenient methods for capturing process output: Process.capture and Process.capture_result.

The new API does not have a shell parameter. If you need shell behaviour, we recommend running a shell explicitly.

These are the most significant individual changes:

Add overloads with combined args parameter instead of command, args (#16681, #16739)
Add Process.run? (#16738)
Add Process.capture (#16773)

All new methods and overloads are experimental. We expect to stabilize the API for the next release.

Thanks @straight-shoota

An io_uring event loop is available for Linux targets and can be selected by specifying -Devloop=io_uring when compiling. The event loop is highly experimental and its performance benefits will differ for every program. We don’t expect it to be faster than epoll, and it may even be slower, except on some benchmarks with SQPOLL enabled.

SQPOLL can be selected by specifying the idle time for the kernel threads with -Dio_uring_sq_thread_idle=200 (for 200ms). It is recommended to keep the idle time low (below 2s), otherwise your CPU cores will regularly spin at 100% usage when doing nothing.

An interesting but potentially surprising behavior is that any I/O call that could yield the calling fiber will now always yield. One benefit is that an always ready socket won’t block other fibers from progressing. A downside is that there might be lots of context switches.

Add io_uring event loop (linux) (#16264)

Thanks @ysbaddaden

Kernel TLS is now supported by default on Linux and FreeBSD as long as support has been compiled into OpenSSL (which should be the default) and enabled on the system (likely disabled by default), for example with modprobe tls on Linux.

Add Kernel TLS support to custom OpenSSL::BIO (#16646)

Thanks @ysbaddaden

Add #select and #reject to HashLiteral and NamedTupleLiteral (#16558)
Refine error message for unsupported named arguments in macros (#16576)

Thanks @Blacksmoke16, @hahwul

OptionParser now supports option bundling and can parse -ncfoo as -n -c foo.

Add short option bundling for OptionParser (#16770)

Thanks @Qard

The OAuth module expected a success response on HTTP OK statuses, but multiple OAuth providers send error responses with an HTTP OK status (sic).

Detect OAuth error in payload (#16634)

Thanks @jgaskins

HTTP::WebSocket can now negotiate sub-protocols.

Add Sec-WebSocket-Protocol checks to HTTP::WebSocket::Protocol (#16600, #16671)
Add support for Sec-WebSocket-Protocol to HTTP::WebSocketHandler (#16574)

Thanks @antondalgren, @straight-shoota

StringScanner saw multiple improvements, ranging from performance to subtle niceties for debugging.

Add StringScanner#scan, #check, and #skip overloads for Int (#16557)
Add StringScanner#peek_behind (#16593)
Add convenience methods to StringScanner (#16595)
Improve cursor window format in StringScanner#inspect (#16594)

Thanks @jneen

The memory management model for libxml2 changed in Crystal 1.17 to become manual instead of integrating the GC. The change introduced another memory leak that is now fixed.

Call xmlFree for the string pointer from xmlNodeGetContent (#16688)

Thanks @toddsundsted

Some additional niceties:

Add IO#read_greedy (#16535)
Add FileUtils#rm_f (#12832)
Add Pointer#align_up and #align_down (#16585)
Add HTTP::Server::Response#content_type and #content_length as convenient accessors (#16712)

Thanks @BlobCodes, @CTC97, @zw963

Prefer modern linker (mold or lld) (#16696)

Thanks @straight-shoota

Parse MacroVar with empty expressions: %var{} (#16772)
Parse ProcNotation with empty arg parenthesis: () -> (#16741)
Add --base-path for crystal docs (#16091)

Thanks @straight-shoota, @matiasgarciaisaia

Support for LLVM 22.1 and 23.0 (#16631)

Thanks @HertzDevil

There is a single deprecation in this release, and it is a trivial one: rename Mutex to Sync::Mutex to use the new algorithm introduced in Crystal 1.19.

We’re experimenting with a two-step mechanism to deprecate a feature. First, we soft deprecate the method in the documentation with a DEPRECATE: callout, then after a few releases we’ll hard deprecate by adding the @[Deprecated] annotation.

Soft deprecate Mutex in favor of Sync::Mutex (#16737)

Thanks @ysbaddaden

Thanks

We have been able to do all of this thanks to the continued support of 84codes and every other sponsor. To maintain and increase the development pace, donations and sponsorships are essential. OpenCollective is available for that.

Reach out to crystal@manas.tech if you’d like to become a direct sponsor or find other ways to support Crystal. We thank you in advance!

Contribute

Crystal 1.19.1 is released!

2026-01-20T00:00:00+00:00

We are announcing a new Crystal release 1.19.1 with two regressions fixed.

See the release notes of 1.19.0 for all the changes introduced in Crystal 1.19.

Pre-built packages are available on GitHub Releases and our official distribution channels. See crystal-lang.org/install for installation instructions.

This release includes 2 changes since 1.19.0 by 1 contributor. We thank all the contributors for all the effort put into improving the language! ❤️

This patch release fixes regressions in timer conversions from absolute to relative time (#16581, #16583) that led sleep(seconds) to immediately trigger instead of waiting on some platforms (Darwin, BSDs, Windows) — both introduced in 1.19.0.

For more details, visit the full changelog.

Thanks

Reach out to crystal@manas.tech if you’d like to become a direct sponsor or find other ways to support Crystal. We thank you in advance!

Contribute

Crystal 1.19.0 is released!

2026-01-15T00:00:00+00:00

We are announcing a new Crystal release 1.19.0 with several new features and bug fixes.

Pre-built packages are available on GitHub Releases and our official distribution channels. See crystal-lang.org/install for installation instructions.

This release includes 237 changes since 1.18.2 by 24 contributors. We thank all the contributors for all the effort put into improving the language! ❤️

Below we list the most remarkable changes in the language, compiler and stdlib. For more details, visit the full changelog.

We do not expect any breaking changes in existing code. If you notice any unexpected issues, please let us know in the issue tracker or forum.

The following changes break prior behavior of the compiler, but we expect them to not have much effect in existing code. If you notice any unexpected issues, please let us know in the issue tracker or forum.

The flag? macro is now aware of name-value mappings in the form of name=value where flag?(:name) will now return the respective value as a StringLiteral (#16310). A key without a value returns true as implicit value, as before.

Instead of returning a BoolLiteral the flag? macro might now return a StringLiteral which might be unexpected. The value is still truthy and shouldn’t cause issues in practice.

For example, the value printed by `` may now be:

(not defined) => false
-Dname => true
-Dname=value => "value"
-Dname=some,other,data => "some,other,data"

Thanks, @straight-shoota

The monotonic clock has been adjusted on Linux and macOS to include suspended time, when they previously counted the system uptime.

UNIX targets still use CLOCK_MONOTONIC except for Linux that now uses CLOCK_BOOTTIME (#16516) and macOS that now uses CLOCK_MONOTONIC_RAW instead of mach_absolute_time that internally used CLOCK_UPTIME_RAW (#16516, #16492).

The change is affecting Time.measure for example, that should now include suspended time across the different targets, rather than sometimes including it, and sometimes not.

Execution contexts from RFC 0002 continue as a final preview feature with opt-in with compiler flags -Dpreview_mt -Dexecution_context and we plan to finally enable the feature by default in the 1.20 release!

There has not been huge developments to the feature, but corrections to fix the remaining thread safety issues in the standard library, for example:

Add thread safety to default random (#16174)
Closing system fd is thread unsafe (#16289)
Thread safety of Exception::Callstack (#16504)

We started to merge synchronization primitives from ysbaddaden/sync into the standard library as well:

Add Sync::Mutex and Sync::RWLock (#16399)
Add Sync::ConditionVariable (#16440)
Add Sync::Exclusive and Sync::Shared (#16487)

This effort is part of the ongoing project to improve multi-threading support with the help of 84codes.

Thanks, @ysbaddaden

Introduces the Time::Instant type to represent instants on the monotonic timeline as defined in RFC 0015 instead of overloading the Time::Span type that represents a duration, not an instant (#16490). We expect a clearer and safer API:

Time::Instant represents a single point on the monotonic timeline.
Time::Span continues to represent a duration.
Subtracting two Time::Instant instances yields a Time::Span.
Adding/subtracting a Time::Span to/from an Time::Instant yields a new Time::Instant.

We also adjusted the monotonic clock (#16516), applied the changes (#16498) and deprecated Time.monotonic (#16545).

For example:

timeout = 5.seconds
start = Time.instant

while start.elapsed < timeout
  # do something
end

In order to migrate existing code to Time::Instant, replace calls to Time.monotonic with Time.instant. If the instant time reading is stored in an explicitly typed variable (e.g. an instance variable), change the type from Time::Span to Time::Instant. The APIs of these types are very similar so most use cases should not need any further adaptions.

Finally, we made some further adjustments:

Treat GMT as a legacy alias of UTC (#16292)
Add /etc/zoneinfo to zoneinfo lookup paths (#16463)
Add support for $TZDIR (#16466)

Thanks, @straight-shoota

A long refactor of spawning sub-processes has started. It encompasses a tedious cleanup and safety fixes related to finding the command as well as building the arguments and environment variables, to eventually move on from the classic fork then exec to the more modern posix_spawn on UNIX targets.

Process.run and Process.exec now look up the target executable in the environment of the parent process (ENV["PATH"]) instead of in the environment of the child process (env["PATH"]) on all platforms (#16340). This is usually the expected and specified behaviour for spawning a new process, but it only worked correcly on Windows until now. Consider using a full path (possibly resolved via Process.find_executable) if you want to look up the executable in a different path. With shell: true, the target executable is also looked up in env["PATH"] because the shell process sits in between.

Create argv before fork (#16286, #16321)
Move make_envp before fork (#16351)
Use execvpe when available (#16294, #16311)
Replace Dir.cd with a non-raising alternative in pre-exec (#16352, #16369)
Fix reset directory if Process.exec fails (#16383)
Disable process cancellation during fork (#16446)

Thanks, @straight-shoota

New methods:

Add NamedTuple#reverse_merge (#16229)
Add Set#map! (#16271)
Add Hash#transform_keys! (#16280)
Add OpenSSL::SSL::Context::Server#on_server_name for SNI (#16452, #16525)
Add IPSocket#ipv6_only (#16347)
Add Int.from_digits as inverse of Int#digits (#16237)
Add BigInt.from_digits (#16259)
Add Int#tdivmod (#16258)
Add Random.next_bool and Random.next_int (#16297)
Add Random#split and Random.split for splittable PRNGs (#16342, #16495)
Add Pointer#fill (#16338)
Add Process.debugger_present? for Windows and Linux (#16248)
Add Path#relative? (#16473)
Add YAML::Nodes.parse_all (#16247)
Add ::exit(Process::Status) (#16436)

Enhancements:

Support large JSON files (#16211)
Support deserialization of YAML anchors of value types (#16186)
Add end locations to scalars and aliases in YAML::Nodes.parse (#16187)
Set JSON::SerializableError#attribute when appropriate (#16158)
Add remove_empty parameter to String#each_line (#16232)
Add weeks parameter to Time::Span.new (#16208)
Support 0X, 0O, 0B prefixes in string to integer conversion (#16226)

Thanks, @andrykonchin, @carlhoerberg, @HertzDevil, @ysbaddaden, @straight-shoota, @RX14, @Sija, @spuun

The memory management model for libxml2 changed in Crystal 1.17 to become manual instead of integrating the GC. The change introduced some memory leaks that have now been fixed.

Memory leak in XML.parse and XML.parse_html methods (#16414)
Memory leak in XML::Document#finalize (#16418)
Memory leak in XML::Node#content= (#16419)
Fix use after unlink in XML::Node (#16432)

Thanks, @toddsundsted

New methods:

Thanks, @Blacksmoke16, @HertzDevil

All overloads of ArrayLiteral#[] return nil on out of bounds (#16453)

Crystal Releases

Crystal 1.20.0 is released!

Stats

Changes

Breaking

Security

Target features

Execution contexts

Process API

io_uring

Kernel TLS

Macros

Standard library

Compiler

Dependencies

Deprecations

Crystal 1.19.1 is released!

Stats

Changes

Crystal 1.19.0 is released!

Stats

Changes

Breaking

Compiler flags now have values

Adjust monotonic clocks

Execution contexts

Time

Process

Standard library

Macros

Compiler

Infra

Dependencies

Deprecations

Crystal 1.18.2 is released!

Stats

Changes

Crystal 1.18.1 is released!

Stats

Changes

Crystal 1.18.0 is released!

Stats

Changes

Execution contexts

Deprecation warnings

Time

Time#inspect

Time::Location

Serialization

Standard library

Networking

Type restrictions

Code Cleanup

Macros

Compiler

Interpreter

Infra

Dependencies

Deprecations

Crystal 1.17.1 is released!

Stats

Changes

Crystal 1.17.0 is released!

Stats

Changes

Breaking

Colorize only on TTY by default

Manual memory management for libxml2

Blocking behaviour of file descriptors

SystemError.from_errno

Execution Contexts and Multi-Threading

Windows Support

Language

Standard library

Time zone database

Scoped IPv6 addresses

Ensuring string suffix and prefix

Time.month_week_date

Helper methods for subclasses

Compiler

`Time#inspect`

`Time::Location`

`Colorize` only on TTY by default

Manual memory management for `libxml2`

`SystemError.from_errno`

`Time.month_week_date`