## Installing extra Python packages for Sage on macOS

To "pip install" extra packages, pip needs to be able
to establish secure connections. This requires the
underlying Python to have its SSL module available.

On most Linux distributions, people normally have OpenSSL
installed as part of their distribution, so we ship Sage
binaries whose Python is compiled with its SSL module,
and it will generally work.

On macOS, Apple uses another way to deal with secure
connection, and does not provide the openssl package
as part of the operating system.

The binaries we ship for macOS don't have OpenSSL because
it was up to now licensed under "the OpenSSL license"
which did not allow to distribute it along with GPL-licensed
software such as Sage.

This is about to change since OpenSSL 3 will be licensed
under the Apache 2.0 license. which will allow distributing
OpenSSL with binaries of GPL-licensed software such as Sage.
So far (2020-04), only a preliminary version of OpenSSL 3
is out. Maybe by the end of 2020 this will be solved for good.

In the meantime, macOS users who want to expand their Sage
with extra Python packages have a few choices, including:

a. download Python packages and install them locally

b. modify one's Sage installation to give its Python the SSL module

c. use a version of Sage whose Python has the SSL module

Below some more details about each of these options.

In terminal commands below, the initial `$`

represents the
shell prompt, it should not be typed, so if you copy-paste
the commands don't include that initial `$`

.

### a. Download Python packages and install them locally

First note that running `sage --pip install packagename`

relies on `packagename`

being available on PyPI
(the Python Package Index).

The PyPI page for `packagename`

is likely:

```
`https://pypi.org/project/packagename`
```

Visit that page in a web browser and find an option there
to download `packagename`

as a zip file, or maybe some other
compressed format, but let's say zip. Download it, and get
a file `packagename.zip`

on your computer, at some location,
let's say in the `Downloads`

folder in your home.

Then run the following (adapt path and filename if needed):

```
$ sage --pip install ~/Downloads/packagename.zip
```

This whole "go visit some webpage, download a zip, and
run `sage --pip install /path/to/packagename.zip`

"
is a little less convenient than the simple
`sage --pip install packagename`

, but at least
it gets the job done and doesn't require any change
to your Sage installation.

In particular, no risk of damaging your Sage installation
and getting it to a non-working state.

### b. Install OpenSSL on an existing Sage installation

There are two ways to do that: b.1 is the easiest,
and b.2 is a little more involved.

#### b.1. Ready-made

The easy way is provided by the developers of
computational topology software packages
(for studying the topology of three-manifolds).
That software can be made to work with Sage
and they found a way to provide just the right
pieces to fix a Sage installation.

Download "fix_mac_sage8.tar.gz" or "fix_mac_sage9.tar.gz"
(respectively for Sage 8.x and Sage 9.x) from the page:

Then unpack and follow the instructions in the
README file found in the unpacked folder.

#### b.2. Rebuilding a lot of things

This is a different way of obtaining the same result
one would get by following b.1.

**Warning:** it takes a lot longer. It leaves you without
a working Sage installation while it is running. In addition,
if it fails, it could break your Sage installation, in which
case you have to reinstall Sage. (In that case you might
want to use option c).

There is a preliminary, which is to have Apple's
"command-line tools for developers" installed.

To install those, run this command in a terminal:

```
$ xcode-select --install
```

This will either tell you that the command-line tools
are already installed, or open a dialog to let you
install them.

Once this is done, it might be a good idea to restart
your computer. Not sure it's needed but it can't hurt.

Now we are almost at the crucial step. This step will
take a long time (up to hours) as it forces the rebuild
of Sage's `python3`

module, which in turn forces to
rebuild all packages that depend on `python3`

(in particular Numpy, Scipy, etc.).

To mitigate that, optionally, set the number of jobs
that `make`

should run in parallel.

To check how many processors can be used, run this:

```
$ sysctl -n hw.ncpu
```

Then, to set `make`

to run say 4 jobs in parallel, run:

```
$ export MAKE='make -j4`
```

Now these two commands should work (but to warn again,
it's happened to me that it did not work and left me with
a broken Sage which I did not know how to repair):

```
$ sage -i openssl
$ sage -f python3 # can take hours
```

If that worked, you should be able to run

```
$ sage --pip install packagename
```

to install any Python package `packagename`

from PyPI.

### c. Installing Sage with SSL support

We now mention ways to perform a complete installation
of Sage with OpenSSL support.

There are several choices including:

install Sage via Conda, see

build Sage from source

- in a Conda environment which has OpenSSL installed
- or with OpenSSL installed via Homebrew
- or without any of Conda or Homebrew

### On several computers

If you have several computers with the same version
of macOS, you might be able to transfer Sage installations
from one to the other, as long as you put them at the
exact same location, for example `/Applications/SageMath`

.

Use your favourite way to transfer files:

- (compress then copy then uncompress)
- rsync
- ...

Careful, a Sage installation can be quite big, so it might
not fit on a USB drive especially if it is formatted as "FAT"
(which does not allow files over 4 GB).

If needed, after compressing to zip or tar-gz or other,
split the file into several parts, put the parts on a
usb drive, and reassemble the parts on the other side.

See this for details: