Skip to content

Update conda instructions #39515

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 12 commits into
base: develop
Choose a base branch
from
Open

Update conda instructions #39515

Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
fce8f14
Do not recommend mambaforge, it is deprecated
saraedum Feb 13, 2025
c1d83bd
Do not recommend mamba
saraedum Feb 13, 2025
8f8c984
No need for SAGE_NUM_THREADS
saraedum Feb 13, 2025
748ba59
Simplify conda installation instructions and normalize layout
saraedum Feb 13, 2025
c454a52
Clarify the channel setup instructions
saraedum Feb 13, 2025
5757729
Explain how to enable JupyterLab in this setup
saraedum Feb 13, 2025
96de3c7
Clarify what the usual linux flavors are in the conda guide
saraedum Feb 13, 2025
109253e
Fix RST errors in conda documentation
saraedum Feb 14, 2025
2d1c409
Fix formatting of texts after code blocks
saraedum Feb 14, 2025
358b507
Drop bullets that do not help readability
saraedum Feb 14, 2025
01ce287
Put SAGE_NUM_THREADS back into the conda instructions
saraedum Feb 14, 2025
6b742c6
Simplify confusing statement about pip install
saraedum Feb 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 54 additions & 65 deletions src/doc/en/installation/conda.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,48 +9,32 @@ SageMath can be installed on Linux and macOS via Conda from the
Both the ``x86_64`` (Intel) architecture and the ``arm64``/``aarch64``
architectures (including Apple Silicon, M1, M2, M3, M4) are supported.

You will need a working Conda installation: either Miniforge (or Mambaforge),
Miniconda or Anaconda. If you don't have one yet, we recommend installing
`Miniforge <https://github.com/conda-forge/miniforge>`_ as
follows. In a terminal,
You will need a working Conda installation: either Miniforge, Miniconda or
Anaconda. If you don't have one yet, we recommend installing `Miniforge
<https://github.com/conda-forge/miniforge>`_ as follows. In a terminal,

.. code-block:: shell

$ curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
$ bash Miniforge3-$(uname)-$(uname -m).sh
$ curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
$ bash Miniforge3-$(uname)-$(uname -m).sh

* Miniforge (and Mambaforge) use conda-forge as the default channel.

* If you are using Miniconda or Anaconda, set it up to use conda-forge:
* Miniforge uses conda-forge as the default channel. However, if you are using
Miniconda or Anaconda, set it up to use conda-forge:

* Add the conda-forge channel: ``conda config --add channels conda-forge``

* Change channel priority to strict: ``conda config --set channel_priority strict``

If you installed Miniforge (or Mambaforge), we recommend to use
`mamba <https://mamba.readthedocs.io/en/latest/index.html>`_ in the following,
which uses a faster dependency solver than ``conda``.

.. _sec-installation-conda-binary:

Installing all of SageMath from conda (not for development)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create a new conda environment containing SageMath, either with ``mamba`` or ``conda``:

.. tab:: mamba

.. code-block:: shell

$ mamba create -n sage sage python=X
Create a new conda environment containing SageMath:

.. tab:: conda

.. code-block:: shell

$ conda create -n sage sage python=X
.. code-block:: shell

where ``X`` is version of Python, e.g. ``3.9``.
$ conda create -n sage sage
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you only keep one, I recommend using mamba. It's drop-in replacement and much faster.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally use mamba but conda works just fine and it is available on the setups that we are covering here (see the top) i.e., also on miniconda and anaconda.

Copy link
Contributor

@vincentmacri vincentmacri Feb 14, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with maintaining conda instructions as I think it's a bit more widely available in various distro repositories. No opinion on keeping both or having just conda.


To use Sage from there,

Expand All @@ -73,51 +57,36 @@ environment for Sage development.

Here we assume that you are using a git checkout.

- Optionally, set the build parallelism for the Sage library. Use
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

think about it, why does this section even exist? isn't https://doc-release--sagemath.netlify.app/html/en/installation/meson enough?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, eventually this section should be removed. But I understood that the meson setup isn't sufficiently stable and some people are using the setup described here.

@tobiasdiez @dimpase do you think that the meson setup should be recommended for everybody that uses conda dependencies and we should just remove this page altogether?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's been a few months since I tried using the meson setup but I remember having issues with it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, in my opinion the meson build is stable enough to be the default for conda-based setups. So I would welcome if we would merge the meson instructions with the conda ones, but would of course understand if you don't want to do this as part of this PR.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vincentmacri would you have the time to try if the meson setup works for you now? I just tried it and it worked fine for me. I'd prefer to delete a page from the documentation if possible.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Meson is still giving me issues. It's possible the problem is on my end, but I'm following the steps in the documentation so if something is wrong on my end I think the meson documentation needs to be updated to be more clear.

On Fedora 41, from the root of the develop branch of my sage fork which has no changes from the develop branch in the sagemath repo:

conda env create --file environment-3.11-linux.yml --name sage-meson
conda activate sage-meson
pip install --no-build-isolation --editable .
./sage

gives the error:

Error in sys.excepthook:
Traceback (most recent call last):
  File "/home/vince/.conda/envs/sage-dev/lib/python3.11/pathlib.py", line 1250, in is_dir
    return S_ISDIR(self.stat().st_mode)
                   ^^^^^^^^^
AttributeError: 'str' object has no attribute 'stat'

Original exception was:
Traceback (most recent call last):
  File "/home/vince/Documents/git/sage/src/bin/sage-ipython", line 15, in <module>
    app.initialize()
  File "/home/vince/.conda/envs/sage-dev/lib/python3.11/site-packages/traitlets/config/application.py", line 118, in inner
    return method(app, *args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vince/.conda/envs/sage-dev/lib/python3.11/site-packages/IPython/terminal/ipapp.py", line 278, in initialize
    self.init_shell()
  File "/home/vince/Documents/git/sage/src/sage/repl/interpreter.py", line 854, in init_shell
    self.shell.extension_manager.load_extension(SAGE_EXTENSION)
  File "/home/vince/.conda/envs/sage-dev/lib/python3.11/site-packages/IPython/core/extensions.py", line 62, in load_extension
    return self._load_extension(module_str)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vince/.conda/envs/sage-dev/lib/python3.11/site-packages/IPython/core/extensions.py", line 79, in _load_extension
    if self._call_load_ipython_extension(mod):
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vince/.conda/envs/sage-dev/lib/python3.11/site-packages/IPython/core/extensions.py", line 129, in _call_load_ipython_extension
    mod.load_ipython_extension(self.shell)
  File "/home/vince/Documents/git/sage/src/sage/repl/__init__.py", line 6, in load_ipython_extension
    sage.repl.ipython_extension.load_ipython_extension(*args)
  File "/home/vince/Documents/git/sage/src/sage/misc/misc.py", line 1029, in wrapper
    result = func(*args, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^
  File "/home/vince/Documents/git/sage/src/sage/repl/ipython_extension.py", line 744, in load_ipython_extension
    SageCustomizations(shell=ip)
  File "/home/vince/Documents/git/sage/src/sage/repl/ipython_extension.py", line 591, in __init__
    import sage.all  # noqa: F401
    ^^^^^^^^^^^^^^^
  File "/home/vince/Documents/git/sage/src/sage/all.py", line 97, in <module>
    from sage.graphs.all import *
  File "/home/vince/Documents/git/sage/src/sage/graphs/all.py", line 9, in <module>
    from sage.graphs.graph import Graph
  File "/home/vince/Documents/git/sage/src/sage/graphs/graph.py", line 436, in <module>
    class Graph(GenericGraph):
  File "/home/vince/Documents/git/sage/src/sage/graphs/graph.py", line 9273, in Graph
    from sage.graphs.connectivity import minimal_separators
ImportError: cannot import name 'minimal_separators' from 'sage.graphs.connectivity' (/home/vince/Documents/git/sage/src/sage/graphs/connectivity.cpython-311-x86_64-linux-gnu.so)
111

Copy link
Contributor

@user202729 user202729 Feb 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/home/vince/Documents/git/sage/src/sage/repl/ipython_extension.py

Implies your sage git repository root is /home/vince/Documents/git/sage/.

ImportError: cannot import name 'minimal_separators' from 'sage.graphs.connectivity' (/home/vince/Documents/git/sage/src/sage/graphs/connectivity.cpython-311-x86_64-linux-gnu.so)

implies the .so file is found right next to the .pyx file.

This should not normally happen, normally meson builds out of source.

Maybe you need to do the following

If you have previously build Sage in-place, you first have to delete the already compiled files, e.g. with shopt -s globstar followed by rm src/**/*.so or for f in src/**/*.so ; do mv "$f" "$f.old"; done. Moreover, remove the old generated files with find src/sage/ext/interpreters -type f ! -name 'meson.build' -delete. Also uninstall the ‘old’ sage packages with pip uninstall sage-conf sage-setup sagemath-standard.

That said, I find git clean -fxd easier (though it might be more brutal because it may remove some user-generated files that is already gitignored)

Copy link
Contributor

@vincentmacri vincentmacri Feb 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had tried what the doc mentioned to remove old generated files before I posted that error. After doing git clean -fxd though everything worked. I guess the meson conda build works for me now. Thanks!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's weird (maybe your shell doesn't support globstar? Are you using something that is not bash?)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's weird (maybe your shell doesn't support globstar? Are you using something that is not bash?)

Nope, I'm using bash.

whatever the meaningful value for your machine is - no more than
the number of cores::

$ export SAGE_NUM_THREADS=24
Create and activate a new conda environment with the dependencies of Sage and a
few additional developer tools; if you are not on a Linux that runs an x86_64
compatible CPU, replace ``linux`` accordingly:

- Create and activate a new conda environment with the dependencies of Sage
and a few additional developer tools:

.. tab:: mamba

.. code-block:: shell

$ mamba env create --file environment-3.11-linux.yml --name sage-dev
$ conda activate sage-dev

.. tab:: conda

.. code-block:: shell

$ conda env create --file environment-3.11-linux.yml --name sage-dev
$ conda activate sage-dev
.. code-block:: shell

Alternatively, you can use ``environment-3.11-linux.yml`` or
``environment-optional-3.11-linux.yml``, which will only install standard
(and optional) packages without any additional developer tools.
$ conda env create --file environment-3.12-linux.yml
$ conda activate sage-dev

A different Python version can be selected by replacing ``3.11`` by ``3.9``
or ``3.10`` in these commands.
Bootstrap the source tree and build the Sage library:

- Bootstrap the source tree and install the build prerequisites and the Sage library::
.. code-block:: shell

$ ./bootstrap
$ pip install --no-build-isolation --config-settings editable_mode=compat -v -v --editable ./src

If you encounter any errors, try to install the ``sage-conf`` package first::
If you encounter any errors, try to install the ``sage-conf`` package first:

.. code-block:: shell

$ pip install --no-build-isolation -v -v --editable ./pkgs/sage-conf_conda

and then run the last command again.
and then run the last command again.

- Verify that Sage has been installed::
Verify that Sage has been installed:

.. code-block:: shell

$ sage -c 'print(version())'
SageMath version 10.2.beta4, Release Date: 2023-09-24
SageMath version 10.5, Release Date: 2024-12-04

Note that ``make`` is not used at all. All dependencies
(including all Python packages) are provided by conda.
Expand All @@ -131,18 +100,38 @@ library is installed in editable mode. This means that when you only
edit Python files, there is no need to rebuild the library; it
suffices to restart Sage.

After editing any Cython files, rebuild the Sage library using::
After editing any Cython files, rebuild the Sage library using:

$ pip install --no-build-isolation --config-settings editable_mode=compat -v -v --editable src
.. code-block:: shell

$ pip install --no-build-isolation --config-settings editable_mode=compat -v -v --editable src

In order to update the conda environment later, you can run:

.. code-block:: shell

In order to update the conda environment later, you can run::
$ conda env update --file environment-3.12-linux.yml

$ mamba env update --file environment-3.11-linux.yml --name sage-dev
If you want to use Jupyter notebooks, you need to install JupyterLab and the SageMath kernel:

To build the documentation, use::
.. code-block:: shell

$ conda install jupyterlab
$ sage -c 'from sage.repl.ipython_kernel.install import SageKernelSpec; SageKernelSpec.update(prefix=sys.prefix)'

To build the documentation, use:

.. code-block:: shell

$ pip install --no-build-isolation -v -v --editable ./pkgs/sage-docbuild
$ sage --docbuild all html

.. NOTE::

$ pip install --no-build-isolation -v -v --editable ./pkgs/sage-docbuild
$ sage --docbuild all html
The build is running in parallel automatically by detecting the number of
execution threads on your CPU. If you want to override this choice
explicitly, you can set ``SAGE_NUM_THREADS``, e.g., by running ``export
SAGE_NUM_THREADS=24`` before invoking ``pip``.

.. NOTE::

Expand All @@ -156,5 +145,5 @@ To build the documentation, use::

You can update the conda lock files by running
``.github/workflows/conda-lock-update.py`` or by running
``conda-lock --platform linux-64 --filename environment-3.11-linux.yml --lockfile environment-3.11-linux.lock``
``conda-lock --platform linux-64 --filename environment-3.12-linux.yml --lockfile environment-3.12-linux.lock``
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated some strings in this file. Not that it really matters but maybe it is going to keep the commands valid literally for a little bit longer.

manually.
Loading