Mamba 2.0 Changes

.. ...................... .. .. THIS IS STILL A DRAFT .. .. ...................... ..

.. TODO high-level summary of new features: .. - OCI registries .. - Mirrors .. - Own implementation repodata.json

Command Line Executables

Mamba (executable)

---

mamba, previously a Python executable mixing libmambapy, conda, and some specific code logic has been entirely replaced by the dynamically linked version of micromamba, a statically-linked ELF based on libmamba.

Hence mamba now has the exact same user interface and experience as micromamba.

.. warning::

The previous code being a highly complex project with few of its original developers still active, it is hard to make an exhaustive list of all changes.

Please help us by reporting changes missing changes.

Micromamba

---

Micromamba receives all new features and its CLI remains mostly unchanged.

Breaking changes include:

• micromamba shell init root prefix parameter --prefix (-p) was renamed --root-prefix (-r). Both options were supported in version 1.5.
• A new config order_solver_request (default true) can be used to order the dependencies passed to the solver, getting order independent solutions.
• Support for complex match specs such as pkg[md5=0000000000000] and pkg[build='^\d*$'].
• For micromamba<=2.1.0: Lost support for leading and internal globs in version strings (via redesigned VersionSpec, which no longer handles version strings as a regex). Only trailing globs were supported.
• Full version regexes, such as ^3.3+$, are not implemented.

.. TODO OCI and mirrors

Libraries

Mamba (Python package)

---

In version 2.0, all tools are fully written in C++. All code previously available in Python through import mamba has been removed.

Libmambapy (Python bindings)

---

The Python bindings to the C++ libmamba library remain available through import libmambapy. They are now considered the first class citizen to using Mamba in Python. Changes include:

• The global Context, previously available through Context(), must now be instantiated at least once before using libmambapy functions and types. Only one instance can exist at any time, but that instance can be destroyed and another recreated later, for example if you use it in specific functions scopes.

  What's more, it is required to be passed explicitly in a few more functions. Notably:

  • MultiPackageCache (constructor)
  • SubdirData.create_repo
  • SubdirIndex.create
  • SubdirIndex.download
  • clean
  • transmute
  • get_virtual_packages
  • cancel_json_output

  In version 2, Context() will throw an exception to allow catching errors more smoothly.

• ChannelContext is no longer an implicit global variable. It must be constructed with one of ChannelContext.make_simple or ChannelContext.make_conda_compatible (with Context.instance as argument in most cases) and passed explicitly to a few functions.

• A new Context independent submodule libmambapy.specs has been introduced with:

  • The redesign of the Channel and a new UnresolvedChannel used to describe unresolved channel strings. A featureful libmambapy.specs.CondaURL is used to describe channel URLs.
  • The redesign of MatchSpec. The module also includes a platform enumeration, an implementation of ordered Version, and a VersionSpec to match versions. Breaking change (for libmambapy<=2.1.0): VersionSpec lost support for leading and internal globs in version strings because they are no longer handled as a regex. Only trailing globs were supported.
  • Full version regexes, such as ^3.3+$, are not implemented in VersionSpec and MatchSpec.
  • PackageInfo has been moved to this submodule. Some attributes have been given a more explicit name fn > filename, url > package_url.

• A new Context independent submodule libmambapy.solver has been introduced with the changes below. A usage documentation page is available at :ref:mamba_usage_solver.

  • The redesign of the Pool, which is now available as libmambapy.solver.libsolv.Database. The new interfaces make it easier to create repositories without using other libmambapy objects.

  • Repo has been redesigned into a lightweight RepoInfo and moved to libmambapy.solver.libsolv. The creation and modification of repos happen through the Database, with methods such as Database.add_repo_from_repodata_json and Database.add_repo_from_packages, but also high-level free functions such as load_subdir_in_database and load_installed_packages_in_database.

  • The Solver has been moved to libmambapy.solver.libsolv.Solver.

    • All jobs, pins, and flags must be passed as a single libmambapy.solver.Request.
    • The outcome of solving the request is either a libmambapy.solver.Solution or a libmambapy.solver.libsolv.Unsolvable state from which rich error messages can be extracted.

For many changes, an exception throwing placeholders has been kept to advise developers on the new direction to take.

Libmamba (C++)

---

The C++ library libmamba has received significant changes. Due to the low usage of the C++ interface, all changes are not listed here. The main changes are:

• Refactoring and testing of a large number of utilities into a util:: namespace.

• Creation of specs:: including the items below. A usage documentation (in Python) is available at :ref:mamba_usage_specs.

  • Implementations of Version and VersionSpec for matching versions,
  • A refactoring of a purely functional Channel class,
  • Implementation of a UnresolvedChannel to describe unresolved Channels,
  • A refactored and complete implementation of MatchSpec using the components above.
  • Breaking change (for libmamba<=2.1.0): VersionSpec lost support for leading and internal globs in version strings because they are no longer handled as a regex. Only trailing globs were supported. This affects version strings in both the command-line interface and recipe requirements.
  • Full version regexes, such as ^3.3+$, are not implemented in VersionSpec and MatchSpec.

• A cleanup of ChannelContext to be a light proxy and parameter holder wrapping the specs::Channel.

• A new repodata.json parser using simdjson <https://simdjson.org/>_.

• The MPool, MRepo and MSolver API has been completely redesigned into a solver subnamespace and works independently of the Context. The solver::libsolv sub-namespace has also been added for full isolation of libsolv, and a solver API without Context. The solver API redesign includes the items below. A usage documentation (in Python) is available at :ref:mamba_usage_solver.

  • A refactoring of the MPool as a DataBase, fully isolates libsolv, and simplifies repository creation.
  • A refactoring and thinning of MRepo as a new RepoInfo.
  • A solver Request with all requirements to solve is the new way to specify jobs.
  • A refactoring of Solver.
  • A solver outcome as either a Solution or an UnSolvable state.

• Plug of the Mamba's MatchSpec implementation in the Solver, enabling the solving of all types of previously unsupported MatchSpecs.

• Improved downloaders.

Mirrors and OCI registries

In the perspective of ensuring continuous and faster access when downloading packages, we now support mirroring channels.

Furthermore, we support fetching packages from OCI registries <https://github.com/opencontainers/distribution-spec/blob/v1.0/spec.md#definitions>_ in order to provide an alternative to hosting on https://conda.anaconda.org/conda-forge/.

Specifying a mirror can be done in the rc file as follows:

.. code::

$ cat ~/.mambarc

Specify a mirror (can be a list of mirrors) for conda-forge channel

mirrored_channels: conda-forge: ["oci://ghcr.io/channel-mirrors/conda-forge"]

repodata_use_zst isn't considered when fetching from oci registries

since compressed repodata is handled internally

(if present, compressed repodata is necessarily fetched)

Setting repodata_use_zst to false avoids useless requests with

zst extension in repodata filename

repodata_use_zst: false

Then, you can for instance create a new environment pandoc_from_oci where pandoc can be fetched from the specified mirror and installed:

.. code::

$ micromamba create -n pandoc_from_oci pandoc -c conda-forge

Listing packages in the created pandoc_from_oci environment:

.. code::

$ micromamba list -n pandoc_from_oci

Name Version Build Channel ────────────────────────────────────────── pandoc 3.2 ha770c72_0 conda-forge