From e39ddf483390e2fc7cbd5a603ac488371fc68d10 Mon Sep 17 00:00:00 2001 From: Antoine Prouvost Date: Mon, 5 May 2025 21:03:23 +0200 Subject: [PATCH] Remove obsolete mamba/micromamba differences (#3924) --- CONTRIBUTING.rst | 3 + .../source/developer_zone/dev_environment.rst | 8 +- docs/source/user_guide/mamba.rst | 234 +++++++++++++-- docs/source/user_guide/micromamba.rst | 268 +----------------- 4 files changed, 225 insertions(+), 288 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index b5da6221c..ee244f84f 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -3,6 +3,9 @@ Contributing ============== The mamba repository is hosted at https://github.com/mamba-org/mamba. +The general developer documentation is hosted at https://mamba.readthedocs.io/en/latest/developer_zone/contributing.html. +See also https://mamba.readthedocs.io/en/latest/developer_zone/dev_environment.html for setting up +a development environment. When contributing to this repository, it is always a good idea to first discuss the change you wish to make via issue, email, or any other method with diff --git a/docs/source/developer_zone/dev_environment.rst b/docs/source/developer_zone/dev_environment.rst index 371207e63..bfc99569b 100644 --- a/docs/source/developer_zone/dev_environment.rst +++ b/docs/source/developer_zone/dev_environment.rst @@ -77,15 +77,15 @@ The tests for libmamba are written in C++. ./build/libmamba/tests/test_libmamba -``micromamba`` integration tests -******************************** +``mamba``/``micromamba`` integration tests +****************************************** -Many ``micromamba`` integration tests are written through a pytest Python wrapper. +Many ``mamba`` integration tests are written through a pytest Python wrapper. The environment variable ``TEST_MAMBA_EXE`` controls which executable is being tested. .. code:: bash - export TEST_MAMBA_EXE="${PWD}/build/micromamba/micromamba" + export TEST_MAMBA_EXE="${PWD}/build/micromamba/mamba" python -m pytest micromamba/tests ``libmambapy`` tests diff --git a/docs/source/user_guide/mamba.rst b/docs/source/user_guide/mamba.rst index 31d178bb9..ec91f3054 100644 --- a/docs/source/user_guide/mamba.rst +++ b/docs/source/user_guide/mamba.rst @@ -17,49 +17,236 @@ The ``mamba create`` command creates a new environment. You can create an environment with the name ``nameofmyenv`` by calling: -.. code:: +.. code:: shell mamba create -n nameofmyenv -After this process has finished, you can _activate_ the virtual environment by calling ``mamba activate ``. -For example, to install JupyterLab from the ``conda-forge`` channel and then run it, you could use the following commands: +After this process has finished, you can :ref:`activate` the virtual environment by +calling ``mamba activate ``. +For example, to install JupyterLab from the ``conda-forge`` channel and then run it, you could use +the following commands: -.. code:: +.. code:: shell mamba create -n myjlabenv jupyterlab -c conda-forge mamba activate myjlabenv # activate our environment jupyter lab # this will start up jupyter lab and open a browser -Once an environment is activated, ``mamba install`` can be used to install further packages into the environment. +Once an environment is activated, ``mamba install`` can be used to install further packages +into the environment. -.. code:: +.. code:: shell mamba activate myjlabenv mamba install bqplot # now you can use bqplot in myjlabenv mamba install "matplotlib>=3.5.0" cartopy # now you installed matplotlib with version>=3.5.0 and default version of cartopy +Instead of activating an environment, you can also execute a command inside the environment by +calling ``mamba run -n ``. +For instance, the previous activation example is similar to: + +.. code:: shell + + mamba run -n myjlabenv jupyter lab + + ``mamba`` vs ``conda`` CLIs =========================== -| ``mamba`` is a drop-in replacement and uses the same commands and configuration options as ``conda``. -| You can swap almost all commands between ``conda`` & ``mamba``: +``mamba`` and ``conda`` mainly have the same command line arguments with a few differences. +For simple cases, you can swap one for the other. +For a full ``conda`` compatible experience, ``conda`` itself uses Mamba's solver under the hood, +so you can get great speedups from previous versions. .. code:: - mamba install ... - mamba create -n ... -c ... ... - mamba list + $ mamba --help + + shell Generate shell init scripts + create Create new environment + install Install packages in active environment + update Update packages in active environment + repoquery Find and analyze packages in active environment or channels + remove, uninstall Remove packages from active environment + list List packages in active environment + package Extract a package or bundle files into an archive + clean Clean package cache + config Configuration of micromamba + info Information about micromamba + constructor Commands to support using micromamba in constructor + env See mamba/micromamba env --help + activate Activate an environment + run Run an executable in an environment + ps Show, inspect or kill running processes + auth Login or logout of a given host + search Find packages in active environment or channels + This is equivalent to `repoquery search` command Specification files =================== -``mamba`` supports the same environment specification file formats as ``conda``. +The ``create`` syntax also allows you to use specification or environment files +(also called *spec files*) to easily re-create environments. -.. important:: +The supported syntaxes are: - While ``micromamba`` :ref:`supports conda-lock "unified" lock - files`, Mamba currently does not. +.. contents:: :local: + +Simple text spec files +********************** + +The ``txt`` file contains *one spec per line*. For example, this could look like: + +.. code:: + + xtensor + numpy 1.19 + xsimd >=7.4 + + +To use this file, pass: + +.. code:: shell + + mamba create -n from_file -f spec_file.txt -c conda-forge + +.. note:: + + You can pass multiple text spec files by repeating the ``-f,--file`` argument. + + +Conda YAML spec files +********************* + +More powerful are ``YAML`` files like the following, because they already contain a desired environment name and the channels to use: + +.. code:: yaml + + name: testenv + channels: + - conda-forge + dependencies: + - python >=3.6,<3.7 + - ipykernel >=5.1 + + - ipywidgets[build_number=!=0] + +They are used the same way as text files: + +.. code:: shell + + mamba create -f env.yml + +.. note:: + CLI options will keep :ref:`precedence` over *target prefix* or *channels* specified in spec files. + +.. note:: + You can pass multiple ``YAML`` spec files by repeating the ``-f,--file`` argument. + +Explicit spec files +******************* + +Using ``conda`` you can generate *explicit* environment lock files. For this, create an environment, activate it, and execute: + +.. code:: shell + + conda list --explicit --md5 + +These environment files look like the following and precisely "pin" the desired package + version + build string. Each package also has a checksum for reproducibility: + +.. code:: + + # This file may be used to create an environment using: + # $ conda create --name --file + # platform: linux-64 + @EXPLICIT + https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2#d7c89558ba9fa0495403155b64376d81 + https://conda.anaconda.org/conda-forge/linux-64/libstdcxx-ng-9.3.0-h2ae2ef3_17.tar.bz2#342f3c931d0a3a209ab09a522469d20c + https://conda.anaconda.org/conda-forge/linux-64/libgomp-9.3.0-h5dbcf3e_17.tar.bz2#8fd587013b9da8b52050268d50c12305 + https://conda.anaconda.org/conda-forge/linux-64/_openmp_mutex-4.5-1_gnu.tar.bz2#561e277319a41d4f24f5c05a9ef63c04 + https://conda.anaconda.org/conda-forge/linux-64/libgcc-ng-9.3.0-h5dbcf3e_17.tar.bz2#fc9f5adabc4d55cd4b491332adc413e0 + https://conda.anaconda.org/conda-forge/linux-64/xtl-0.6.21-h0efe328_0.tar.bz2#9eee90b98fd394db7a049792e67e1659 + https://conda.anaconda.org/conda-forge/linux-64/xtensor-0.21.8-hc9558a2_0.tar.bz2#1030174db5c183f3afb4181a0a02873d + +To install such a file with ``mamba``, just pass the ``-f`` flag again: + +.. code:: shell + + mamba create -n xtensor -f explicit_env.txt + +.. note:: + + Explicit spec files are single-platform. + +``conda-lock`` YAML spec files +****************************** + +Using ``conda-lock``, you can generate lockfiles which, like explicit spec files, pin precisely and include a checksum for each package for reproducibility. +Unlike explicit spec files, these "unified" lock files are multi-platform. + +These files are named ``conda-lock.yml`` by default, and look like: + +.. code:: + + # This lock file was generated by conda-lock (https://github.com/conda/conda-lock). DO NOT EDIT! + # + # A "lock file" contains a concrete list of package versions (with checksums) to be installed. Unlike + # e.g. `conda env create`, the resulting environment will not change as new package versions become + # available, unless you explicitly update the lock file. + # + # Install this environment as "YOURENV" with: + # conda-lock install -n YOURENV --file conda-lock.yml + # To update a single package to the latest version compatible with the version constraints in the source: + # conda-lock lock --lockfile conda-lock.yml --update PACKAGE + # To re-solve the entire environment, e.g. after changing a version constraint in the source file: + # conda-lock -f environment.yml --lockfile conda-lock.yml + version: 1 + metadata: + content_hash: + osx-64: c2ccd3a86813af18ea19782a2f92b5a82e01c89f64a020ad6dea262aae638e48 + linux-64: 06e0621a9712fb0dc0b16270ddb3e0be16982b203fc71ffa07408bf4bb7c22ec + win-64: efee77261626b3877b9d7cf7bf5bef09fd8e5ddfc79349a5f598ea6c8891ee84 + channels: + - url: conda-forge + used_env_vars: [] + platforms: + - linux-64 + - osx-64 + - win-64 + sources: + - environment.yml + package: + - name: _libgcc_mutex + version: '0.1' + manager: conda + platform: linux-64 + dependencies: {} + url: https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2 + hash: + md5: d7c89558ba9fa0495403155b64376d81 + sha256: fe51de6107f9edc7aa4f786a70f4a883943bc9d39b3bb7307c04c41410990726 + category: main + optional: false + - name: ca-certificates + version: 2023.5.7 + manager: conda + platform: linux-64 + dependencies: {} + url: https://conda.anaconda.org/conda-forge/linux-64/ca-certificates-2023.5.7-hbcca054_0.conda + hash: + md5: f5c65075fc34438d5b456c7f3f5ab695 + sha256: 0cf1bb3d0bfc5519b60af2c360fa4888fb838e1476b1e0f65b9dbc48b45c7345 + category: main + optional: false + +In order to YAML files to be considered as ``conda-lock`` files, their name must ends with ``-lock.yml`` or ``-lock.yaml``. + +To install such a file with ``mamba``, just pass the ``-f`` flag again: + +.. code:: + + $ mamba create -n my-environment -f conda-lock.yml Repoquery ========= @@ -69,26 +256,26 @@ To efficiently query repositories and query package dependencies you can use ``m Here are some examples: -.. code:: +.. code:: shell # will show you all available xtensor packages. - $ mamba repoquery search xtensor + mamba repoquery search xtensor # you can also specify more constraints on this search query - $ mamba repoquery search "xtensor>=0.18" + mamba repoquery search "xtensor>=0.18" # will show you a list of the direct dependencies of xtensor. - $ mamba repoquery depends xtensor + mamba repoquery depends xtensor # will show you a list of the dependencies (including dependencies of dependencies). - $ mamba repoquery depends xtensor --recursive + mamba repoquery depends xtensor --recursive The flag ``--recursive`` shows also recursive (i.e. transitive) dependencies of dependent packages instead of only direct dependencies. With the ``-t,--tree`` flag, you can get the same information of a recursive query in a tree. .. code:: - $ mamba repoquery depends -t xtensor + mamba repoquery depends -t xtensor xtensor == 0.21.5 ├─ libgcc-ng [>=7.3.0] @@ -107,7 +294,7 @@ And you can ask for the inverse, which packages depend on some other package (e. .. code:: - $ mamba repoquery whoneeds ipython + mamba repoquery whoneeds ipython Name Version Build Depends Channel ------------------------------------------------------------------- @@ -120,7 +307,7 @@ With the ``-t,--tree`` flag, you can get the same information in a tree. .. code:: - $ mamba repoquery whoneeds -t ipython + mamba repoquery whoneeds -t ipython ipython[8.2.0] ├─ jupyter_console[6.4.3] @@ -140,5 +327,6 @@ With the ``-t,--tree`` flag, you can get the same information in a tree. .. note:: + ``depends`` and ``whoneeds`` sub-commands require either the specified package to be installed in you environment, or for the channel to be specified with the ``-c,--channel`` flag. When ``search`` sub-command is used without specifying the **channel** explicitly (using the flag previously mentioned), the search will be performed considering the channels set during the configuration. diff --git a/docs/source/user_guide/micromamba.rst b/docs/source/user_guide/micromamba.rst index b49341cf5..4613c2384 100644 --- a/docs/source/user_guide/micromamba.rst +++ b/docs/source/user_guide/micromamba.rst @@ -8,270 +8,16 @@ Micromamba User Guide It is a statically linked C++ executable with a separate command line interface. It does not need a ``base`` environment and does not come with a default version of Python. - -Quickstarts -=========== - -| ``micromamba`` supports a subset of all ``mamba`` or ``conda`` commands and implements a command line interface from scratch. -| You can see all implemented commands with ``micromamba --help``: - -.. code:: - - $ micromamba --help - - Subcommands: - shell Generate shell init scripts - create Create new environment - install Install packages in active environment - update Update packages in active environment - repoquery Find and analyze packages in active environment or channels - remove Remove packages from active environment - list List packages in active environment - package Extract a package or bundle files into an archive - clean Clean package cache - config Configuration of micromamba - info Information about micromamba - constructor Commands to support using micromamba in constructor - env See `mamba/micromamba env --help` - activate Activate an environment - run Run an executable in an environment - ps Show, inspect or kill running processes - auth Login or logout of a given host - search Find packages in active environment or channels - - -To activate an environment just call ``micromamba activate /path/to/env`` or, when it's a named environment in your :ref:`root prefix`, then you can also use ``micromamba activate myenv``. - -``micromamba`` expects to find the *root prefix* set by ``$MAMBA_ROOT_PREFIX`` environment variable. You can also provide it using CLI option ``-r,--root-prefix``. - - | Named environments then live in ``$MAMBA_ROOT_PREFIX/envs/``. - -For more details, please read about :ref:`configuration`. - -After :ref:`activation`, you can run ``install`` to add new packages to the environment. - -.. code:: - - $ micromamba install xtensor -c conda-forge - - -Using ``create``, you can also create environments: - -.. code:: - - $ micromamba create -n xtensor_env xtensor xsimd -c conda-forge - __ - __ ______ ___ ____ _____ ___ / /_ ____ _ - / / / / __ `__ \/ __ `/ __ `__ \/ __ \/ __ `/ - / /_/ / / / / / / /_/ / / / / / / /_/ / /_/ / - / .___/_/ /_/ /_/\__,_/_/ /_/ /_/_.___/\__,_/ - /_/ - - conda-forge/noarch [====================] (00m:01s) Done - conda-forge/linux-64 [====================] (00m:04s) Done - - Transaction - - Prefix: /home/wolfv/miniconda3/envs/xtensor_env - - Updating specs: - - - xtensor - - xsimd - - - Package Version Build Channel Size - ──────────────────────────────────────────────────────────────────────── - Install: - ──────────────────────────────────────────────────────────────────────── - - _libgcc_mutex 0.1 conda_forge conda-forge/linux-64 Cached - _openmp_mutex 4.5 1_gnu conda-forge/linux-64 Cached - libgcc-ng 9.3.0 h5dbcf3e_17 conda-forge/linux-64 Cached - libgomp 9.3.0 h5dbcf3e_17 conda-forge/linux-64 Cached - libstdcxx-ng 9.3.0 h2ae2ef3_17 conda-forge/linux-64 Cached - xsimd 7.4.9 hc9558a2_0 conda-forge/linux-64 102 KB - xtensor 0.21.9 h0efe328_0 conda-forge/linux-64 183 KB - xtl 0.6.21 h0efe328_0 conda-forge/linux-64 Cached - - Summary: - - Install: 8 packages - - Total download: 285 KB - - ──────────────────────────────────────────────────────────────────────── - - Confirm changes: [Y/n] ... - - -After the installation is finished, the environment can be :ref:`activated` with: - -.. code:: - - $ micromamba activate xtensor_env - - -Specification files -=================== - -The ``create`` syntax also allows you to use specification or environment files (also called *spec files*) to easily re-create environments. - -The supported syntaxes are: - -.. contents:: :local: - -Simple text spec files -********************** - -The ``txt`` file contains *one spec per line*. For example, this could look like: - -.. code:: - - xtensor - numpy 1.19 - xsimd >=7.4 - - -To use this file, pass: - -.. code:: - - $ micromamba create -n from_file -f spec_file.txt -c conda-forge - -.. note:: - You can pass multiple text spec files by repeating the ``-f,--file`` argument. - - -Conda YAML spec files -********************* - -More powerful are ``YAML`` files like the following, because they already contain a desired environment name and the channels to use: - -.. code:: - - name: testenv - channels: - - conda-forge - dependencies: - - python >=3.6,<3.7 - - ipykernel >=5.1 - - ipywidgets[build_number=!=0] - -They are used the same way as text files: - -.. code:: - - $ micromamba create -f env.yml - -.. note:: - CLI options will keep :ref:`precedence` over *target prefix* or *channels* specified in spec files. - -.. note:: - You can pass multiple ``YAML`` spec files by repeating the ``-f,--file`` argument. - -Explicit spec files -******************* - -Using ``conda`` you can generate *explicit* environment lock files. For this, create an environment, activate it, and execute: - -.. code:: - - $ conda list --explicit --md5 - -These environment files look like the following and precisely "pin" the desired package + version + build string. Each package also has a checksum for reproducibility: - -.. code:: - - # This file may be used to create an environment using: - # $ conda create --name --file - # platform: linux-64 - @EXPLICIT - https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2#d7c89558ba9fa0495403155b64376d81 - https://conda.anaconda.org/conda-forge/linux-64/libstdcxx-ng-9.3.0-h2ae2ef3_17.tar.bz2#342f3c931d0a3a209ab09a522469d20c - https://conda.anaconda.org/conda-forge/linux-64/libgomp-9.3.0-h5dbcf3e_17.tar.bz2#8fd587013b9da8b52050268d50c12305 - https://conda.anaconda.org/conda-forge/linux-64/_openmp_mutex-4.5-1_gnu.tar.bz2#561e277319a41d4f24f5c05a9ef63c04 - https://conda.anaconda.org/conda-forge/linux-64/libgcc-ng-9.3.0-h5dbcf3e_17.tar.bz2#fc9f5adabc4d55cd4b491332adc413e0 - https://conda.anaconda.org/conda-forge/linux-64/xtl-0.6.21-h0efe328_0.tar.bz2#9eee90b98fd394db7a049792e67e1659 - https://conda.anaconda.org/conda-forge/linux-64/xtensor-0.21.8-hc9558a2_0.tar.bz2#1030174db5c183f3afb4181a0a02873d - -To install such a file with ``micromamba``, just pass the ``-f`` flag again: - -.. code:: - - $ micromamba create -n xtensor -f explicit_env.txt - .. note:: - Explicit spec files are single-platform. + ``mamba`` and ``micromamba`` are the same code base, only build options vary. -.. _micromamba-conda-lock: +In combinations with subcommands like ``micromamba shell`` and ``micromamba run``, it is extremely +convenient in CI and Docker environments where running shell activatio hooks is complicated. -``conda-lock`` YAML spec files -****************************** +I can be used with a drop-in installation without further steps: -Using ``conda-lock``, you can generate lockfiles which, like explicit spec files, pin precisely and include a checksum for each package for reproducibility. -Unlike explicit spec files, these "unified" lock files are multi-platform. +.. code-block:: shell -These files are named ``conda-lock.yml`` by default, and look like: - -.. code:: - - # This lock file was generated by conda-lock (https://github.com/conda/conda-lock). DO NOT EDIT! - # - # A "lock file" contains a concrete list of package versions (with checksums) to be installed. Unlike - # e.g. `conda env create`, the resulting environment will not change as new package versions become - # available, unless you explicitly update the lock file. - # - # Install this environment as "YOURENV" with: - # conda-lock install -n YOURENV --file conda-lock.yml - # To update a single package to the latest version compatible with the version constraints in the source: - # conda-lock lock --lockfile conda-lock.yml --update PACKAGE - # To re-solve the entire environment, e.g. after changing a version constraint in the source file: - # conda-lock -f environment.yml --lockfile conda-lock.yml - version: 1 - metadata: - content_hash: - osx-64: c2ccd3a86813af18ea19782a2f92b5a82e01c89f64a020ad6dea262aae638e48 - linux-64: 06e0621a9712fb0dc0b16270ddb3e0be16982b203fc71ffa07408bf4bb7c22ec - win-64: efee77261626b3877b9d7cf7bf5bef09fd8e5ddfc79349a5f598ea6c8891ee84 - channels: - - url: conda-forge - used_env_vars: [] - platforms: - - linux-64 - - osx-64 - - win-64 - sources: - - environment.yml - package: - - name: _libgcc_mutex - version: '0.1' - manager: conda - platform: linux-64 - dependencies: {} - url: https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2 - hash: - md5: d7c89558ba9fa0495403155b64376d81 - sha256: fe51de6107f9edc7aa4f786a70f4a883943bc9d39b3bb7307c04c41410990726 - category: main - optional: false - - name: ca-certificates - version: 2023.5.7 - manager: conda - platform: linux-64 - dependencies: {} - url: https://conda.anaconda.org/conda-forge/linux-64/ca-certificates-2023.5.7-hbcca054_0.conda - hash: - md5: f5c65075fc34438d5b456c7f3f5ab695 - sha256: 0cf1bb3d0bfc5519b60af2c360fa4888fb838e1476b1e0f65b9dbc48b45c7345 - category: main - optional: false - -In order to YAML files to be considered as ``conda-lock`` files, their name must ends with ``-lock.yml`` or ``-lock.yaml``. - -To install such a file with ``micromamba``, just pass the ``-f`` flag again: - -.. code:: - - $ micromamba create -n my-environment -f conda-lock.yml + /path/to/micromamba create -p /tmp/env 'pytest>=8.0' + /path/to/micromamba run -p /tmp/env pytest myproject/tests