Elixir Dependencies

Elixir is a dynamic, functional language for building scalable and maintainable applications. When you build applications you are going to use libraries. Libraries can be either open source like Phoenix or privately created libraries. This post is some general notes on Elixir and dependency management. Please check the actual Elixir documentation (for your particular version) to get the most accurate answers to any questions.

• https://hexdocs.pm/mix/1.1.1/Mix.Tasks.Deps.html
• https://hexdocs.pm/hex/Mix.Tasks.Hex.Outdated.html
• https://hexdocs.pm/hex/Mix.Tasks.Hex.Audit.html
• https://hexdocs.pm/elixir/dependencies-and-umbrella-projects.html

Where Do Dependencies Come From?

A mix.exs file exists for a mix project. The file defines a module and the module has the statement: use Mix.Project. Example:

defmodule Xyz.MixProject do
  use Mix.Project

  <etc, etc>

See Mix.Project for detailed information. An implementation of a project/0 function is required in the module. This function returns a keyword list representing configuration for the project. One of keyword items is :deps. This is a list of dependencies of this project. Defaults to [].

Dependencies are specified in a particular way (described below). When dependencies are fetched mix creates a mix.lock file. This file has the final resolved dependency information and is what is used for building your software.

Project Structure

The mix.exs and mix.lock files exist in different places and with slightly different rules depending on the choice of project structure.

It’s probably useful to go over project structure before talking about library dependencies since you may run into three project organizations in Elixir. The project organization has an impact on the mechanics of dependency management.

Flat Project

The first type of project is flat/standard. This is the type of structure that you get if you invoke mix phx.new. For a Phoenix web app generated with:

mix phx.new --no-html --no-live --no-tailwind \
    --no-esbuild --no-mailer xyz

you’d get a general directory structure like this:

/xyz
  mix.exs
  mix.lock
  /lib
    /xyz
    /xyz_web

In a flat structure all the dependencies are put in the top-level mix.exs file. Performing a mix deps.get creates and populates the mix.lock file.

Umbrella Project

The second type of project is an umbrella project. You can generate a Phoenix app as an umbrella project using the --umbrella option. For a Phoenix web app generated with:

mix phx.new --no-html --no-live --no-tailwind \
  --no-esbuild --no-mailer --umbrella xyz

you’d get a general directory structure like this:

/xyz
  mix.exs
  mix.lock
  /apps
    /xyz
      mix.exs
    /xyz_web
      mix.exs

In an umbrella structure the top-level mix.exs file has a deps/0 function. However, the deps are available only for this project and cannot be accessed from applications inside the apps/ folder. For example, you might add a dependency on credo so you can run credo over all the apps source code.

The actual dependencies are contained in the mix.exs files for the two apps subdirectories xyz and xyz_wen. Note that you can have as many “apps” as you want in the /apps directory and each would have its own mix.exs file. Two are generated by default. The xyz directory is meant to hold “business logic”. The xyz_web directory is meant to hold “all the code dealing with web requests”.

The umbrella project structure is recognized by mix. When you mix deps.get from the command line a mix.lock file is created at the top-level. This file will contain dependencies from both xyz and xyz_web mix.exs files.

Poncho Project

The third project type is a poncho project. Poncho projects are common in embedded Elixir (Nerves) projects. You may also find this approach in Phoenix code. In a poncho app the top-level mix.exs uses a path to indicate where code is. That means that could separate code into different directories but you are not required to have it all under an “apps” directory.

Unlike an umbrella project, a poncho project will usually have a mix.lock file in each of the subdirectories referenced in the top-level mix.exs file. The subdirectories are compiled more like library dependencies.

To compile the project each of your local directories that are under your project directory. Then go to the top level project directory to build the release. You don’t have the ability to run mix test from the top level and have it run mix test on all the code in all of your directories.

Version Information

Elixir projects are required to follow the version format outlined in the SemVer 2.0 schema. A version is identified by three numbers: MAJOR.MINOR.PATCH.

There is additional information in the Elixir documentation on how to handle pre-releases and build information:

Pre-releases are supported by optionally appending a hyphen and a series of period-separated identifiers immediately following the patch version. Identifiers consist of only ASCII alphanumeric characters and hyphens ([0-9A-Za-z-]).

"1.0.0-alpha.3"

Build information can be added by appending a plus sign and a series of dot-separated identifiers immediately following the patch or pre-release version. Identifiers consist of only ASCII alphanumeric characters and hyphens ([0-9A-Za-z-]):

"1.0.0-alpha.3+20130417140000.amd64"

SemVer naming actually has rules. These rules are not enforced by Elixir but it’s important to know what they are and to know whether dependencies you are using are observing the rules. The rules are important because developers, in general, expect them to be observed. Here are the rules:

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes
• MINOR version when you add functionality in a backward compatible manner
• PATCH version when you make backward compatible bug fixes

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

Assuming all your dependent libraries are following these rules you can make a choice on how much risk to introduce in managing your dependencies via a dependent’s requirements.

Dependencies and Requirements

When you specify that your code depends on a library you setup a requirement for it. One part of the requirement is where the library can be found: hex.pm, github, etc. Another part is which version of the library you want. To specify the version you can use the common comparison operators such as >, >=, <, <=, and ==. These work just like you’d imagine. Here’s some examples:

Requirements also support and and or for complex conditions:

      # 2.0.0 and later until 2.1.0
      ">= 2.0.0 and < 2.1.0"

This is such a common requirement that there is a “special” operator to express it: “~>”.

    # 2.0.0 and later until 2.1.0
    "~> 2.0.0"

The “~>” operator indicates that the highest least-significant digit version of the library can be used. So, in the example, “~> 2.0.0” means that “2.0.0”, “2.0.1”, “2.0.2”, etc can be used but “2.1.0” cannot.

This means if you only specify MAJOR and MINOR digits you are allowing any MINOR digit but the MAJOR must match. So “~> 2.0” means that “2.0.0”, “2.1.7”, “2.5.4” are all acceptable.

The most common case is to specify down to the PATCH. This allows bug fixes but blocks backward compatible changes.

Your approach needs to examine whether the library you are dependent on is actually following the SemVer rules. Most (if not all) of them will.

Options for Requirements

There are a number of options available when specifying a requirement for a dependency. Here are some common options you’ll see (for a complete list of options consult the Mix.Tasks.Dep documentation).

• :optional - this marks the dependency as optional. In such cases, the current project will always include the optional dependency but any other project that depends on the current project won’t be forced to use the optional dependency. However, if the other project includes the optional dependency on its own, the requirements and options specified here will also be applied. Optional dependencies will not be started by the application. You should consider compiling your projects with the mix compile –no-optional-deps –warnings-as-errors during test, to ensure your project compiles without warnings even if optional dependencies are missing
• :only - the dependency is made available only in the given environments, useful when declaring dev- or test-only dependencies
• :override - if set to true the dependency will override any other definitions of itself by other dependencies

Overriding a Library Dependency

You can run into issues where one library you are using requires one version of a library while a second library requires a different version. The requirements are in conflict and the app won’t compile unless you intervene.

One way to intervene is to specify the version to use in your app’s dependencies using the option override: true. Be aware that if you override across a MAJOR version you may cause serious issues with your app. It’s important to understand why a library has specified an older version of a library. In many cases its simply that the library specifying the older version is not being maintained or not maintained at a rate that aligns with the other library you are using. However, that is not necessarily the case.

Mix.lock

The mix.lock file is generated when you run mix deps.get. This is the file that contains all of the dependencies for the project. It includes not only the dependencies declared in your mix.exs file but also all of the dependencies of your libraries. For example, for a Phoenix generated project the mix.lock file looks like this:

%{
  "bandit": {:hex, :bandit, "1.6.8", "be6fcbe01a74e6cba42ae35f4085acaeae9b2d8d360c0908d0b9addbc2811e47", [:mix], [{:hpax, "~> 1.0", [hex: :hpax, repo: "hexpm", optional: false]}, {:plug, "~> 1.14", [hex: :plug, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}, {:thousand_island, "~> 1.0", [hex: :thousand_island, repo: "hexpm", optional: false]}, {:websock, "~> 0.5", [hex: :websock, repo: "hexpm", optional: false]}], "hexpm", "4fc08c8d4733735d175a007ecb25895e84d09292b0180a2e9f16948182c88b6e"},
  "castore": {:hex, :castore, "1.0.12", "053f0e32700cbec356280c0e835df425a3be4bc1e0627b714330ad9d0f05497f", [:mix], [], "hexpm", "3dca286b2186055ba0c9449b4e95b97bf1b57b47c1f2644555879e659960c224"},
  "db_connection": {:hex, :db_connection, "2.7.0", "b99faa9291bb09892c7da373bb82cba59aefa9b36300f6145c5f201c7adf48ec", [:mix], [{:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "dcf08f31b2701f857dfc787fbad78223d61a32204f217f15e881dd93e4bdd3ff"},
  "decimal": {:hex, :decimal, "2.3.0", "3ad6255aa77b4a3c4f818171b12d237500e63525c2fd056699967a3e7ea20f62", [:mix], [], "hexpm", "a4d66355cb29cb47c3cf30e71329e58361cfcb37c34235ef3bf1d7bf3773aeac"},
  "dns_cluster": {:hex, :dns_cluster, "0.1.3", "0bc20a2c88ed6cc494f2964075c359f8c2d00e1bf25518a6a6c7fd277c9b0c66", [:mix], [], "hexpm", "46cb7c4a1b3e52c7ad4cbe33ca5079fbde4840dedeafca2baf77996c2da1bc33"},
  "ecto": {:hex, :ecto, "3.12.5", "4a312960ce612e17337e7cefcf9be45b95a3be6b36b6f94dfb3d8c361d631866", [:mix], [{:decimal, "~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "6eb18e80bef8bb57e17f5a7f068a1719fbda384d40fc37acb8eb8aeca493b6ea"},
  "ecto_sql": {:hex, :ecto_sql, "3.12.1", "c0d0d60e85d9ff4631f12bafa454bc392ce8b9ec83531a412c12a0d415a3a4d0", [:mix], [{:db_connection, "~> 2.4.1 or ~> 2.5", [hex: :db_connection, repo: "hexpm", optional: false]}, {:ecto, "~> 3.12", [hex: :ecto, repo: "hexpm", optional: false]}, {:myxql, "~> 0.7", [hex: :myxql, repo: "hexpm", optional: true]}, {:postgrex, "~> 0.19 or ~> 1.0", [hex: :postgrex, repo: "hexpm", optional: true]}, {:tds, "~> 2.1.1 or ~> 2.2", [hex: :tds, repo: "hexpm", optional: true]}, {:telemetry, "~> 0.4.0 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "aff5b958a899762c5f09028c847569f7dfb9cc9d63bdb8133bff8a5546de6bf5"},
  "expo": {:hex, :expo, "1.1.0", "f7b9ed7fb5745ebe1eeedf3d6f29226c5dd52897ac67c0f8af62a07e661e5c75", [:mix], [], "hexpm", "fbadf93f4700fb44c331362177bdca9eeb8097e8b0ef525c9cc501cb9917c960"},
  "gettext": {:hex, :gettext, "0.26.2", "5978aa7b21fada6deabf1f6341ddba50bc69c999e812211903b169799208f2a8", [:mix], [{:expo, "~> 0.5.1 or ~> 1.0", [hex: :expo, repo: "hexpm", optional: false]}], "hexpm", "aa978504bcf76511efdc22d580ba08e2279caab1066b76bb9aa81c4a1e0a32a5"},
  "hpax": {:hex, :hpax, "1.0.2", "762df951b0c399ff67cc57c3995ec3cf46d696e41f0bba17da0518d94acd4aac", [:mix], [], "hexpm", "2f09b4c1074e0abd846747329eaa26d535be0eb3d189fa69d812bfb8bfefd32f"},
  "jason": {:hex, :jason, "1.4.4", "b9226785a9aa77b6857ca22832cffa5d5011a667207eb2a0ad56adb5db443b8a", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "c5eb0cab91f094599f94d55bc63409236a8ec69a21a67814529e8d5f6cc90b3b"},
  "mime": {:hex, :mime, "2.0.6", "8f18486773d9b15f95f4f4f1e39b710045fa1de891fada4516559967276e4dc2", [:mix], [], "hexpm", "c9945363a6b26d747389aac3643f8e0e09d30499a138ad64fe8fd1d13d9b153e"},
  "phoenix": {:hex, :phoenix, "1.7.20", "6bababaf27d59f5628f9b608de902a021be2cecefb8231e1dbdc0a2e2e480e9b", [:mix], [{:castore, ">= 0.0.0", [hex: :castore, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:phoenix_pubsub, "~> 2.1", [hex: :phoenix_pubsub, repo: "hexpm", optional: false]}, {:phoenix_template, "~> 1.0", [hex: :phoenix_template, repo: "hexpm", optional: false]}, {:phoenix_view, "~> 2.0", [hex: :phoenix_view, repo: "hexpm", optional: true]}, {:plug, "~> 1.14", [hex: :plug, repo: "hexpm", optional: false]}, {:plug_cowboy, "~> 2.7", [hex: :plug_cowboy, repo: "hexpm", optional: true]}, {:plug_crypto, "~> 1.2 or ~> 2.0", [hex: :plug_crypto, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}, {:websock_adapter, "~> 0.5.3", [hex: :websock_adapter, repo: "hexpm", optional: false]}], "hexpm", "6be2ab98302e8784a31829e0d50d8bdfa81a23cd912c395bafd8b8bfb5a086c2"},
  "phoenix_ecto": {:hex, :phoenix_ecto, "4.6.3", "f686701b0499a07f2e3b122d84d52ff8a31f5def386e03706c916f6feddf69ef", [:mix], [{:ecto, "~> 3.5", [hex: :ecto, repo: "hexpm", optional: false]}, {:phoenix_html, "~> 2.14.2 or ~> 3.0 or ~> 4.1", [hex: :phoenix_html, repo: "hexpm", optional: true]}, {:plug, "~> 1.9", [hex: :plug, repo: "hexpm", optional: false]}, {:postgrex, "~> 0.16 or ~> 1.0", [hex: :postgrex, repo: "hexpm", optional: true]}], "hexpm", "909502956916a657a197f94cc1206d9a65247538de8a5e186f7537c895d95764"},
  "phoenix_html": {:hex, :phoenix_html, "4.2.1", "35279e2a39140068fc03f8874408d58eef734e488fc142153f055c5454fd1c08", [:mix], [], "hexpm", "cff108100ae2715dd959ae8f2a8cef8e20b593f8dfd031c9cba92702cf23e053"},
  "phoenix_live_dashboard": {:hex, :phoenix_live_dashboard, "0.8.6", "7b1f0327f54c9eb69845fd09a77accf922f488c549a7e7b8618775eb603a62c7", [:mix], [{:ecto, "~> 3.6.2 or ~> 3.7", [hex: :ecto, repo: "hexpm", optional: true]}, {:ecto_mysql_extras, "~> 0.5", [hex: :ecto_mysql_extras, repo: "hexpm", optional: true]}, {:ecto_psql_extras, "~> 0.7", [hex: :ecto_psql_extras, repo: "hexpm", optional: true]}, {:ecto_sqlite3_extras, "~> 1.1.7 or ~> 1.2.0", [hex: :ecto_sqlite3_extras, repo: "hexpm", optional: true]}, {:mime, "~> 1.6 or ~> 2.0", [hex: :mime, repo: "hexpm", optional: false]}, {:phoenix_live_view, "~> 0.19 or ~> 1.0", [hex: :phoenix_live_view, repo: "hexpm", optional: false]}, {:telemetry_metrics, "~> 0.6 or ~> 1.0", [hex: :telemetry_metrics, repo: "hexpm", optional: false]}], "hexpm", "1681ab813ec26ca6915beb3414aa138f298e17721dc6a2bde9e6eb8a62360ff6"},
  "phoenix_live_view": {:hex, :phoenix_live_view, "1.0.5", "f072166f87c44ffaf2b47b65c5ced8c375797830e517bfcf0a006fe7eb113911", [:mix], [{:floki, "~> 0.36", [hex: :floki, repo: "hexpm", optional: true]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:phoenix, "~> 1.6.15 or ~> 1.7.0", [hex: :phoenix, repo: "hexpm", optional: false]}, {:phoenix_html, "~> 3.3 or ~> 4.0", [hex: :phoenix_html, repo: "hexpm", optional: false]}, {:phoenix_template, "~> 1.0", [hex: :phoenix_template, repo: "hexpm", optional: false]}, {:phoenix_view, "~> 2.0", [hex: :phoenix_view, repo: "hexpm", optional: true]}, {:plug, "~> 1.15", [hex: :plug, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4.2 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "94abbc84df8a93a64514fc41528695d7326b6f3095e906b32f264ec4280811f3"},
  "phoenix_pubsub": {:hex, :phoenix_pubsub, "2.1.3", "3168d78ba41835aecad272d5e8cd51aa87a7ac9eb836eabc42f6e57538e3731d", [:mix], [], "hexpm", "bba06bc1dcfd8cb086759f0edc94a8ba2bc8896d5331a1e2c2902bf8e36ee502"},
  "phoenix_template": {:hex, :phoenix_template, "1.0.4", "e2092c132f3b5e5b2d49c96695342eb36d0ed514c5b252a77048d5969330d639", [:mix], [{:phoenix_html, "~> 2.14.2 or ~> 3.0 or ~> 4.0", [hex: :phoenix_html, repo: "hexpm", optional: true]}], "hexpm", "2c0c81f0e5c6753faf5cca2f229c9709919aba34fab866d3bc05060c9c444206"},
  "plug": {:hex, :plug, "1.17.0", "a0832e7af4ae0f4819e0c08dd2e7482364937aea6a8a997a679f2cbb7e026b2e", [:mix], [{:mime, "~> 1.0 or ~> 2.0", [hex: :mime, repo: "hexpm", optional: false]}, {:plug_crypto, "~> 1.1.1 or ~> 1.2 or ~> 2.0", [hex: :plug_crypto, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4.3 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "f6692046652a69a00a5a21d0b7e11fcf401064839d59d6b8787f23af55b1e6bc"},
  "plug_crypto": {:hex, :plug_crypto, "2.1.0", "f44309c2b06d249c27c8d3f65cfe08158ade08418cf540fd4f72d4d6863abb7b", [:mix], [], "hexpm", "131216a4b030b8f8ce0f26038bc4421ae60e4bb95c5cf5395e1421437824c4fa"},
  "postgrex": {:hex, :postgrex, "0.20.0", "363ed03ab4757f6bc47942eff7720640795eb557e1935951c1626f0d303a3aed", [:mix], [{:db_connection, "~> 2.1", [hex: :db_connection, repo: "hexpm", optional: false]}, {:decimal, "~> 1.5 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:table, "~> 0.1.0", [hex: :table, repo: "hexpm", optional: true]}], "hexpm", "d36ef8b36f323d29505314f704e21a1a038e2dc387c6409ee0cd24144e187c0f"},
  "telemetry": {:hex, :telemetry, "1.3.0", "fedebbae410d715cf8e7062c96a1ef32ec22e764197f70cda73d82778d61e7a2", [:rebar3], [], "hexpm", "7015fc8919dbe63764f4b4b87a95b7c0996bd539e0d499be6ec9d7f3875b79e6"},
  "telemetry_metrics": {:hex, :telemetry_metrics, "1.1.0", "5bd5f3b5637e0abea0426b947e3ce5dd304f8b3bc6617039e2b5a008adc02f8f", [:mix], [{:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "e7b79e8ddfde70adb6db8a6623d1778ec66401f366e9a8f5dd0955c56bc8ce67"},
  "telemetry_poller": {:hex, :telemetry_poller, "1.1.0", "58fa7c216257291caaf8d05678c8d01bd45f4bdbc1286838a28c4bb62ef32999", [:rebar3], [{:telemetry, "~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "9eb9d9cbfd81cbd7cdd24682f8711b6e2b691289a0de6826e58452f28c103c8f"},
  "thousand_island": {:hex, :thousand_island, "1.3.11", "b68f3e91f74d564ae20b70d981bbf7097dde084343c14ae8a33e5b5fbb3d6f37", [:mix], [{:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "555c18c62027f45d9c80df389c3d01d86ba11014652c00be26e33b1b64e98d29"},
  "websock": {:hex, :websock, "0.5.3", "2f69a6ebe810328555b6fe5c831a851f485e303a7c8ce6c5f675abeb20ebdadc", [:mix], [], "hexpm", "6105453d7fac22c712ad66fab1d45abdf049868f253cf719b625151460b8b453"},
  "websock_adapter": {:hex, :websock_adapter, "0.5.8", "3b97dc94e407e2d1fc666b2fb9acf6be81a1798a2602294aac000260a7c4a47d", [:mix], [{:bandit, ">= 0.6.0", [hex: :bandit, repo: "hexpm", optional: true]}, {:plug, "~> 1.14", [hex: :plug, repo: "hexpm", optional: false]}, {:plug_cowboy, "~> 2.6", [hex: :plug_cowboy, repo: "hexpm", optional: true]}, {:websock, "~> 0.5", [hex: :websock, repo: "hexpm", optional: false]}], "hexpm", "315b9a1865552212b5f35140ad194e67ce31af45bcee443d4ecb96b5fd3f3782"},
}

You can see lots of libraries that are not in the project’s deps/0 list. For example, castore and plug.

Its an interesting file to look at. Our deps/0 list contains:

{:phoenix, "~> 1.7.20"}

The mix.lock file has:

"phoenix": {:hex, :phoenix, "1.7.20", \
"6bababaf27d59f5628f9b608de902a021be2cecefb8231e1dbdc0a2e2e480e9b", [:mix], \
[{:castore, ">= 0.0.0", [hex: :castore, repo: "hexpm", optional: false]}, \
{:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, \
{:phoenix_pubsub, "~> 2.1", [hex: :phoenix_pubsub, repo: "hexpm", optional: \
false]}, {:phoenix_template, "~> 1.0", [hex: :phoenix_template, repo: "hexpm", \
optional: false]}, {:phoenix_view, "~> 2.0", [hex: :phoenix_view, repo: \
"hexpm", optional: true]}, {:plug, "~> 1.14", [hex: :plug, repo: "hexpm", \
optional: false]}, {:plug_cowboy, "~> 2.7", [hex: :plug_cowboy, repo: "hexpm", \
optional: true]}, {:plug_crypto, "~> 1.2 or ~> 2.0", [hex: :plug_crypto, repo: \
"hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, \
repo: "hexpm", optional: false]}, {:websock_adapter, "~> 0.5.3", [hex: \
:websock_adapter, repo: "hexpm", optional: false]}], "hexpm", \
"6be2ab98302e8784a31829e0d50d8bdfa81a23cd912c395bafd8b8bfb5a086c2"}

The mix.lock entry starts with the library name (“phoenix”:). It then has a tuple indicating the library is pulled from hex.pm and it has the version of the library that was indicated in the mix.exs file (in this particular case).

As shown in the section on “Dependencies and Requirements” the version that ends up in the mix.lock file can be different from the version specified in the mix.exs file. It will meet the requirements that you specify. If the requirements cannot be met then the build fails.

The information in the mix.lock file is used during the build process. It isn’t used to indicate how the code is actually deployed. In the mix.exs file you can specify releases under the project. This is a list allowing multiple entries. Each entry specifies something that can be released independently. You can look at the doc for ‘mix release’ for more information.

CI and Dependencies

For applications I recommend that developers check in the mix.lock file for your application. Your CI builds should use:

mix deps.get --check-locked

The documentation for mix deps.get command line options indicates that this will raise if performing the get of the dependency would result in a change to the mix.lock file.

The reason to do this is to ensure that what you build and deploy matches what developers are using in their own environments to test their code. It catches changes that are unexpected. After figuring out the change and deciding its fine you can update your mix.lock file to resolve the issue. If the change might cause a problem then you’ll have to use a tighter restriction on the fetched dependencies so that your production code uses the version you want.

Dependency Conflicts

If your app is dependent on libraries and libraries are dependent on other libraries then there can be conflicts. These occur when a requirement for a library in one mix.exs file conflicts with the requirement in another. For example, here are two statements that have a conflict that the compiler cannot resolve.

{:phoenix, "< 1.7"}
{:phoenix, ">= 1.7.6"}

The Phoenix library cannot be both below version 1.7 and greater than or less than 1.7.6. The compile will fail.

It is up to the developer to resolve these type of conflicts. The app can only have one version of the Phoenix library loaded.

It is possible to force an override in your application’s mix.exs if you have issues like this. For example:

{:phoenix, ">= 1.7.6", override: true}

This generally requires an investigation to ensure you are not just going to break a library when you override to force a version the library has not declared as compatible.

Checking If Dependencies Are Up To Date

There is a built in command in mix to allow you to check if your dependency is up to date:

mix hex.outdated

As long as the dependencies you use are in hex.pm this will output information that tells you that a library is “Up-to-date”, “Update possible” or “Update not possible”.

If this outputs “Update not possible” then it means that you cannot get the most current library without modifying your requirement specification for the library. That is, you’ll have to edit your mix.exs file manually.

It’s important to run this on a consistent basis to be aware of when your dependencies are falling behind the current releases. Keeping your dependencies up to date will save you lots of heartache.

It’s important to review a CHANGELOG.md for a library (assuming it has one) before updating a dependency. Although its important to keep your dependencies updated, its much more important to ensure that your application actually functions. Be careful. Read through the changes done to a library and test thoroughly in a non-production environment before updating your dependency.

My Library Is Abandoned

Open source software is wonderful. But if you are writing an app you might use a library that has only a single maintainer. This might work perfectly well when you first deploy your application. But it can be multiple years later and you are still using the version that you originally depended on because no releases have been done for the library.

I’d suggest attempting to contact the library author. Add issues to their project to indicate why its important that the library is updated. Create pull requests to perform the needed updates.

If the library author seems unreachable then you really have to fork the repo and begin developing and maintaining the software out of the new repo. I’d add to the README.md file to indicate what you are doing and why. I’d keep the library public so you might possibly also be able to leverage other folks in the Elixir open source community. At this point you are no longer using hex.pm and will have to reference the github location in your library requirement.