View Source Compatibility and deprecations

Elixir is versioned according to a vMAJOR.MINOR.PATCH schema.

Elixir is currently at major version v1. A new backwards compatible minor release happens every 6 months. Patch releases are not scheduled and are made whenever there are bug fixes or security patches.

Elixir applies bug fixes only to the latest minor branch. Security patches are available for the last 5 minor branches:

Elixir versionSupport
1.17Bug fixes and security patches
1.16Security patches only
1.15Security patches only
1.14Security patches only
1.13Security patches only

New releases are announced in the read-only announcements mailing list. All security releases will be tagged with [security].

There are currently no plans for a major v2 release.

Between non-major Elixir versions

Elixir minor and patch releases are backwards compatible: well-defined behaviors and documented APIs in a given version will continue working on future versions.

Although we expect the vast majority of programs to remain compatible over time, it is impossible to guarantee that no future change will break any program. Under some unlikely circumstances, we may introduce changes that break existing code:

  • Security: a security issue in the implementation may arise whose resolution requires backwards incompatible changes. We reserve the right to address such security issues.

  • Bugs: if an API has undesired behavior, a program that depends on the buggy behavior may break if the bug is fixed. We reserve the right to fix such bugs.

  • Compiler front-end: improvements may be done to the compiler, introducing new warnings for ambiguous modes and providing more detailed error messages. Those can lead to compilation errors (when running with --warning-as-errors) or tooling failures when asserting on specific error messages (although one should avoid such). We reserve the right to do such improvements.

  • Imports: new functions may be added to the Kernel module, which is auto-imported. They may collide with local functions defined in your modules. Collisions can be resolved in a backwards compatible fashion using import Kernel, except: [...] with a list of all functions you don't want to be imported from Kernel. We reserve the right to do such additions.

In order to continue evolving the language without introducing breaking changes, Elixir will rely on deprecations to demote certain practices and promote new ones. Our deprecation policy is outlined in the "Deprecations" section.

The only exception to the compatibility guarantees above are experimental features, which will be explicitly marked as such, and do not provide any compatibility guarantee until they are stabilized.

Between Elixir and Erlang/OTP

Erlang/OTP versioning is independent from the versioning of Elixir. Erlang releases a new major version yearly. Our goal is to support the last three Erlang major versions by the time Elixir is released. The compatibility table is shown below.

Elixir versionSupported Erlang/OTP versions
1.1725 - 27
1.1624 - 26
1.1524 - 26
1.1423 - 25 (and Erlang/OTP 26 from v1.14.5)
1.1322 - 24 (and Erlang/OTP 25 from v1.13.4)
1.1222 - 24
1.1121 - 23 (and Erlang/OTP 24 from v1.11.4)
1.1021 - 22 (and Erlang/OTP 23 from v1.10.3)
1.920 - 22
1.820 - 22
1.719 - 22
1.619 - 20 (and Erlang/OTP 21 from v1.6.6)
1.518 - 20
1.418 - 19 (and Erlang/OTP 20 from v1.4.5)
1.318 - 19
1.218 - 18 (and Erlang/OTP 19 from v1.2.6)
1.117 - 18
1.017 - 17 (and Erlang/OTP 18 from v1.0.5)

Elixir may add compatibility to new Erlang/OTP versions on patch releases, such as support for Erlang/OTP 20 in v1.4.5. Those releases are made for convenience and typically contain the minimum changes for Elixir to run without errors, if any changes are necessary. Only the next minor release, in this case v1.5.0, effectively leverages the new features provided by the latest Erlang/OTP release.

Deprecations

Policy

Elixir deprecations happen in 3 steps:

  1. The feature is soft-deprecated. It means both CHANGELOG and documentation must list the feature as deprecated but no warning is effectively emitted by running the code. There is no requirement to soft-deprecate a feature.

  2. The feature is effectively deprecated by emitting warnings on usage. This is also known as hard-deprecation. In order to deprecate a feature, the proposed alternative MUST exist for AT LEAST THREE minor versions. For example, Enum.uniq/2 was soft-deprecated in favor of Enum.uniq_by/2 in Elixir v1.1. This means a deprecation warning may only be emitted by Elixir v1.4 or later.

  3. The feature is removed. This can only happen on major releases. This means deprecated features in Elixir v1.x shall only be removed by Elixir v2.x.

Table of deprecations

The first column is the version the feature was hard deprecated. The second column shortly describes the deprecated feature and the third column explains the replacement and from which the version the replacement is available from.

VersionDeprecated featureReplaced by (available since)
v1.17Single-quoted charlists ('foo')~c"foo" (v1.0)
v1.17left..right in patterns and guardsleft..right//step (v1.11)
v1.17ExUnit.Case.register_test/4register_test/6 (v1.10)
v1.17:all in IO.read/2 and IO.binread/2:eof (v1.13)
v1.16~R/.../~r/.../ (v1.0)
v1.16Ranges with negative steps in Enum.slice/2Explicit steps in ranges (v1.11)
v1.16Ranges with negative steps in String.slice/2Explicit steps in ranges (v1.11)
v1.15Calendar.ISO.day_of_week/3Calendar.ISO.day_of_week/4 (v1.11)
v1.15Exception.exception?/1Kernel.is_exception/1 (v1.11)
v1.15Regex.regex?/1Kernel.is_struct/2 (Kernel.is_struct(term, Regex)) (v1.11)
v1.15Logger.warn/2Logger.warning/2 (v1.11)
v1.14use Bitwiseimport Bitwise (v1.0)
v1.14~~~/1bnot/2 (v1.0)
v1.14Application.get_env/3 and similar in module bodyApplication.compile_env/3 (v1.10)
v1.14Compiled patterns in String.starts_with?/2Pass a list of strings instead (v1.0)
v1.14Mix.Tasks.Xref.calls/1Compilation tracers (outlined in Code) (v1.10)
v1.14$levelpad in LoggerNone
v1.14<|> as a custom operatorAnother custom operator (v1.0)
v1.13! and != in Version requirements~> or >= (v1.0)
v1.13Mix.ConfigConfig (v1.9)
v1.13:strip_beam config to mix escript.build:strip_beams (v1.9)
v1.13Macro.to_string/2Macro.to_string/1 (v1.0)
v1.13System.get_pid/0System.pid/0 (v1.9)
v1.12^^^/2bxor/2 (v1.0)
v1.12@foo() to read module attributesRemove the parenthesis (v1.0)
v1.12use EEx.EngineExplicitly delegate to EEx.Engine instead (v1.0)
v1.12:xref compiler in MixNothing (it always runs as part of the compiler now)
v1.11Mix.Project.compile/2Mix.Task.run("compile", args) (v1.0)
v1.11Supervisor.Spec.worker/3 and Supervisor.Spec.supervisor/3The new child specs outlined in Supervisor (v1.5)
v1.11Supervisor.start_child/2 and Supervisor.terminate_child/2DynamicSupervisor (v1.6)
v1.11System.stacktrace/1__STACKTRACE__ in try/catch/rescue (v1.7)
v1.10Code.ensure_compiled?/1Code.ensure_compiled/1 (v1.0)
v1.10Code.load_file/2Code.require_file/2 (v1.0) or Code.compile_file/2 (v1.7)
v1.10Code.loaded_files/0Code.required_files/0 (v1.7)
v1.10Code.unload_file/1Code.unrequire_files/1 (v1.7)
v1.10Passing non-chardata to Logger.log/2Explicitly convert to string with to_string/1 (v1.0)
v1.10:compile_time_purge_level in Logger app environment:compile_time_purge_matching in Logger app environment (v1.7)
v1.10Supervisor.Spec.supervise/2The new child specs outlined in Supervisor (v1.5)
v1.10:simple_one_for_one strategy in SupervisorDynamicSupervisor (v1.6)
v1.10:restart and :shutdown in Task.Supervisor.start_link/1:restart and :shutdown in Task.Supervisor.start_child/3 (v1.6)
v1.9Enumerable keys in Map.drop/2, Map.split/2, and Map.take/2Call Enum.to_list/1 on the second argument before hand (v1.0)
v1.9Mix.Project.load_paths/1Mix.Project.compile_path/1 (v1.0)
v1.9Passing :insert_replaced to String.replace/4Use :binary.replace/4 (v1.0)
v1.8Passing a non-empty list to Collectable.into/1++/2 or Keyword.merge/2 (v1.0)
v1.8Passing a non-empty list to :into in for/1++/2 or Keyword.merge/2 (v1.0)
v1.8Passing a non-empty list to Enum.into/2++/2 or Keyword.merge/2 (v1.0)
v1.8Time units in its plural form, such as: :seconds, :milliseconds, and the likeUse the singular form, such as: :second, :millisecond, and so on (v1.4)
v1.8Inspect.Algebra.surround/3Inspect.Algebra.concat/2 and Inspect.Algebra.nest/2 (v1.0)
v1.8Inspect.Algebra.surround_many/6Inspect.Algebra.container_doc/6 (v1.6)
v1.9--detached in Kernel.CLI--erl "-detached" (v1.0)
v1.8Kernel.ParallelCompiler.files/2Kernel.ParallelCompiler.compile/2 (v1.6)
v1.8Kernel.ParallelCompiler.files_to_path/2Kernel.ParallelCompiler.compile_to_path/2 (v1.6)
v1.8Kernel.ParallelRequire.files/2Kernel.ParallelCompiler.require/2 (v1.6)
v1.8Returning {:ok, contents} or :error from Mix.Compilers.Erlang.compile/6's callbackReturn {:ok, contents, warnings} or {:error, errors, warnings} (v1.6)
v1.8System.cwd/0 and System.cwd!/0File.cwd/0 and File.cwd!/0 (v1.0)
v1.7Code.get_docs/2Code.fetch_docs/1 (v1.7)
v1.7Enum.chunk/2,3,4Enum.chunk_every/2 and Enum.chunk_every/3,4 (v1.5)
v1.7Calling super/1 inGenServer callbacksImplementing the behaviour explicitly without calling super/1 (v1.0)
v1.7not left in rightleft not in right (v1.5)
v1.7Registry.start_link/3Registry.start_link/1 (v1.5)
v1.7Stream.chunk/2,3,4Stream.chunk_every/2 and Stream.chunk_every/3,4 (v1.5)
v1.6Enum.partition/2Enum.split_with/2 (v1.4)
v1.6Macro.unescape_tokens/1,2Use Enum.map/2 to traverse over the arguments (v1.0)
v1.6Module.add_doc/6@doc module attribute (v1.0)
v1.6Range.range?/1Pattern match on _.._ (v1.0)
v1.5() to mean nilnil (v1.0)
v1.5char_list/0 typecharlist/0 type (v1.3)
v1.5Atom.to_char_list/1Atom.to_charlist/1 (v1.3)
v1.5Enum.filter_map/3Enum.filter/2 + Enum.map/2 or for/1 comprehensions (v1.0)
v1.5Float.to_char_list/1Float.to_charlist/1 (v1.3)
v1.5GenEvent moduleSupervisor and GenServer (v1.0);<br/>GenStage (v1.3);<br/>:gen_event (Erlang/OTP 17)
v1.5<%= in middle and end expressions in EExUse <% (<%= is allowed only in start expressions) (v1.0)
v1.5:as_char_lists value in Inspect.Opts.t/0 type:as_charlists value (v1.3)
v1.5:char_lists key in Inspect.Opts.t/0 type:charlists key (v1.3)
v1.5Integer.to_char_list/1,2Integer.to_charlist/1 and Integer.to_charlist/2 (v1.3)
v1.5to_char_list/1to_charlist/1 (v1.3)
v1.5List.Chars.to_char_list/1List.Chars.to_charlist/1 (v1.3)
v1.5@compile {:parse_transform, _} in ModuleNone
v1.5Stream.filter_map/3Stream.filter/2 + Stream.map/2 (v1.0)
v1.5String.ljust/3 and String.rjust/3Use String.pad_leading/3 and String.pad_trailing/3 with a binary padding (v1.3)
v1.5String.lstrip/1 and String.rstrip/1String.trim_leading/1 and String.trim_trailing/1 (v1.3)
v1.5String.lstrip/2 and String.rstrip/2Use String.trim_leading/2 and String.trim_trailing/2 with a binary as second argument (v1.3)
v1.5String.strip/1 and String.strip/2String.trim/1 and String.trim/2 (v1.3)
v1.5String.to_char_list/1String.to_charlist/1 (v1.3)
v1.4Anonymous functions with no expression after ->Use an expression or explicitly return nil (v1.0)
v1.4Support for making private functions overridableUse public functions (v1.0)
v1.4Variable used as function callUse parentheses (v1.0)
v1.4Access.key/1Access.key/2 (v1.3)
v1.4Behaviour module@callback module attribute (v1.0)
v1.4Enum.uniq/2Enum.uniq_by/2 (v1.2)
v1.4Float.to_char_list/2:erlang.float_to_list/2 (Erlang/OTP 17)
v1.4Float.to_string/2:erlang.float_to_binary/2 (Erlang/OTP 17)
v1.4HashDict moduleMap (v1.2)
v1.4HashSet moduleMapSet (v1.1)
v1.4IEx.Helpers.import_file/2IEx.Helpers.import_file_if_available/1 (v1.3)
v1.4Mix.Utils.camelize/1Macro.camelize/1 (v1.2)
v1.4Mix.Utils.underscore/1Macro.underscore/1 (v1.2)
v1.4Multi-letter aliases in OptionParserUse single-letter aliases (v1.0)
v1.4Set moduleMapSet (v1.1)
v1.4Stream.uniq/2Stream.uniq_by/2 (v1.2)
v1.3\x{X*} inside strings/sigils/charlists\uXXXX or \u{X*} (v1.1)
v1.3Dict moduleKeyword (v1.0) or Map (v1.2)
v1.3:append_first option in defdelegate/2Define the function explicitly (v1.0)
v1.3Map/dictionary as 2nd argument in Enum.group_by/3Enum.reduce/3 (v1.0)
v1.3Keyword.size/1length/1 (v1.0)
v1.3Map.size/1map_size/1 (v1.0)
v1.3/r option in Regex/U (v1.1)
v1.3Set behaviourMapSet data structure (v1.1)
v1.3String.valid_character?/1String.valid?/1 (v1.0)
v1.3Task.find/2Use direct message matching (v1.0)
v1.3Non-map as 2nd argument in URI.decode_query/2Use a map (v1.0)
v1.2Dict behaviourMap and Keyword (v1.0)
v1.1?\xHEX0xHEX (v1.0)
v1.1Access protocolAccess behaviour (v1.1)
v1.1as: true | false in alias/2 and require/2None