You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: source/install.md
+24-24Lines changed: 24 additions & 24 deletions
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,10 @@
1
1
# Installation
2
2
3
-
OpenFF software is distributed via [Conda Forge], a repository of software packages maintained by the open source community. You need a Conda-compatible package manager to install Conda Forge software. OpenFF recommends [Mamba], installed via the [MambaForge] distribution.
3
+
OpenFF software is distributed via [Conda Forge], a repository of software packages maintained by the open source community. You need a Conda-compatible package manager to install Conda Forge software. OpenFF recommends [Mamba], installed via the [Miniforge] distribution.
@@ -15,25 +15,25 @@ This guide describes how to install OpenFF software within your own user account
15
15
If you have an existing Mamba installation, skip steps 1 and 2 below. If you have an existing Conda installation, see [](existing_conda).
16
16
:::
17
17
18
-
1. Download the appropriate MambaForge installer from the [MambaForge repository]. Use [Mambaforge-MacOSX-x86_64] on a Mac and [Mambaforge-Linux-x86_64] on Linux/WSL.
18
+
1. Download the appropriate Miniforge installer from the [Miniforge repository]. Use [Miniforge-MacOSX-x86_64] on a Mac and [Miniforge-Linux-x86_64] on Linux/WSL.
19
19
20
-
2. Run the MambaForge installer in a terminal window and accept the license agreement:
20
+
2. Run the Miniforge installer in a terminal window and accept the license agreement:
21
21
22
22
```shell-session
23
-
$ bash Mambaforge-$(uname)-x86_64.sh
23
+
$ bash Miniforge-$(uname)-x86_64.sh
24
24
```
25
25
26
26
1. When asked for an install destination, choose a directory owned by your user account (such as the default).
27
27
28
-
2. When asked if you'd like to initialize MambaForge, answer "yes". Note that this will modify your shell's startup script; for more information about this choice, see [](conda_init).
28
+
2. When asked if you'd like to initialize Miniforge, answer "yes". Note that this will modify your shell's startup script; for more information about this choice, see [](conda_init).
29
29
30
-
3. Once the installer is finished, close the window and run the following command in a new terminal window:
30
+
3. Once the installer is finished, close the window and run the following command in a new terminal window:
31
31
32
32
```shell-session
33
33
$ conda config --set auto_activate_base false
34
34
```
35
35
36
-
3. Close and reopen the terminal window and install the desired packages into a [new environment]. The names of OpenFF packages can be found in the [projects list]:
36
+
3. Close and reopen the terminal window and install the desired packages into a [new environment]. The names of OpenFF packages can be found in the [projects list]:
@@ -50,16 +50,16 @@ If you have an existing Mamba installation, skip steps 1 and 2 below. If you hav
50
50
If that worked, you're all set! The rest of this page covers corner cases and how to manage Conda environments. For package-specific installation instructions, please see the individual [project docs].
51
51
52
52
:::{admonition} OpenFF on Windows
53
-
We recommend installing MambaForge through WSL on Windows. For more information, see [](install_windows).
53
+
We recommend installing Miniforge through WSL on Windows. For more information, see [](install_windows).
54
54
:::
55
55
56
56
:::{admonition} OpenFF on Apple Silicon
57
-
If you run into issues with upstream dependencies not supporting Apple Silicon, we recommend installing x86_64 MambaForge. For more information, see [](install_arm).
57
+
If you run into issues with upstream dependencies not supporting Apple Silicon, we recommend installing x86_64 Miniforge. For more information, see [](install_arm).
@@ -70,35 +70,35 @@ If you run into issues with upstream dependencies not supporting Apple Silicon,
70
70
(install_mamba)=
71
71
## Installing Mamba
72
72
73
-
Mamba is a drop-in replacement for the Conda package manager. It is faster and can sometimes find ways to safely install two pieces of software that Conda thinks have conflicting dependencies. MambaForge includes Mamba itself, as well as an initial configuration supporting Conda Forge.
73
+
Mamba is a drop-in replacement for the Conda package manager. It is faster and can sometimes find ways to safely install two pieces of software that Conda thinks have conflicting dependencies. Miniforge includes Mamba itself, as well as an initial configuration supporting Conda Forge.
74
74
75
-
If you don't have Conda or Mamba installed, installing MambaForge will give you access to everything you need to install OpenFF software. If you can, we recommend installing MambaForge locally to your user account, rather than system-wide, so that you can freely create and destroy environments and manage your own configuration. If something goes wrong, you can always delete your MambaForge installation and start again, and you'll only lose your installed software.
75
+
If you don't have Conda or Mamba installed, installing Miniforge will give you access to everything you need to install OpenFF software. If you can, we recommend installing Miniforge locally to your user account, rather than system-wide, so that you can freely create and destroy environments and manage your own configuration. If something goes wrong, you can always delete your Miniforge installation and start again, and you'll only lose your installed software.
76
76
77
77
Mamba can be installed to your own user account without root/sudo access. A system-wide multi-user Conda/Mamba installation is [complicated] and generally not necessary.
78
78
79
79
:::{hint}
80
-
If you're running Mamba through MambaForge, you're configured to use the Conda Forge channel by default, and you don't need to pass the `-c conda-forge` argument to the commands in this page. Including this argument does no harm, so we've included it for the benefit of users that don't have this configuration.
80
+
If you're running Mamba through Miniforge, you're configured to use the Conda Forge channel by default, and you don't need to pass the `-c conda-forge` argument to the commands in this page. Including this argument does no harm, so we've included it for the benefit of users that don't have this configuration.
After it's done installing, the MambaForge installer will ask you if you want it to initialize MambaForge. Initialization involves adding a section to your shell startup script that tells the shell where to find Conda/Mamba. Answering "no" will leave you startup scripts untouched, but you will need to run an additional command every time you want to use Conda/Mamba or a Conda environment. Answering "yes" will attempt to add a version of this command to your shell startup script, which generally makes Conda easier to use.
88
+
After it's done installing, the Miniforge installer will ask you if you want it to initialize Miniforge. Initialization involves adding a section to your shell startup script that tells the shell where to find Conda/Mamba. Answering "no" will leave you startup scripts untouched, but you will need to run an additional command every time you want to use Conda/Mamba or a Conda environment. Answering "yes" will attempt to add a version of this command to your shell startup script, which generally makes Conda easier to use.
89
89
90
90
If you do answer "yes", we recommend preventing Conda from activating the base environment in every new shell:
91
91
92
92
```shell-session
93
93
$ conda config --set auto_activate_base false
94
94
```
95
95
96
-
This will prevent any conflicts between the MambaForge Python installation and the Python expected by your system. It does not prevent you from using Conda/Mamba directly to manage or activate environments.
96
+
This will prevent any conflicts between the Miniforge Python installation and the Python expected by your system. It does not prevent you from using Conda/Mamba directly to manage or activate environments.
97
97
98
98
(existing_conda)=
99
99
### Installing Mamba in an existing Conda installation
100
100
101
-
If you already have Conda installed, you don't need to install MambaForge; you can install Mamba on its own into the base environment with:
101
+
If you already have Conda installed, you don't need to install Miniforge; you can install Mamba on its own into the base environment with:
102
102
103
103
```shell-session
104
104
$ conda install -n base -c conda-forge mamba
@@ -118,10 +118,10 @@ Conda environments that use packages from Conda Forge alongside packages from th
In environments with this configuration, the `-c conda-forge` switch is unnecessary. Other channels, like `psi4` and `bioconda`, can still be used in the usual way. These settings can be applied to all your Conda environments by removing the `--env` switches, matching the default MambaForge configuration.
124
+
In environments with this configuration, the `-c conda-forge` switch is unnecessary. Other channels, like `psi4` and `bioconda`, can still be used in the usual way. These settings can be applied to all your Conda environments by removing the `--env` switches, matching the default Miniforge configuration.
125
125
126
126
(managing_environments)=
127
127
## Managing Environments
@@ -158,7 +158,7 @@ $ jupyter-lab .
158
158
159
159
### Advanced Environment Management
160
160
161
-
Mamba/Conda cache the packages you install, so if you've already downloaded a particular version, you can install it in as many environments as you like without having to re-download it. In fact, Mamba/Conda try their hardest to unpack each version once, and then hardlink to it from each environment to keep the storage size of environments down. So don't be afraid to just create a new environment!
161
+
Mamba/Conda cache the packages you install, so if you've already downloaded a particular version, you can install it in as many environments as you like without having to re-download it. In fact, Mamba/Conda try their hardest to unpack each version once, and then hardlink to it from each environment to keep the storage size of environments down. So don't be afraid to just create a new environment!
162
162
163
163
Because of this linking behavior, package code is often shared among different environments. If you edit one environment's `lib/python/site-packages` directory for example, those changes are likely to affect other environments. If you want to tinker with the code of your dependencies, consider using the `--copy` argument when installing them to avoid linking!
OpenFF does not support or test on Windows natively. All of our software is pure Python code and may work anyway as long as you can provide our dependencies, but many of these dependencies are not available on Windows and may not be in the foreseeable future.
235
235
236
-
Instead, we recommend using the [Windows Subsystem for Linux] to run OpenFF software on Windows. WSL runs a Linux kernel within your Windows system so you can run ordinary software as if you had a Linux system. If your hardware supports it, we suggest using WSL2 for a smoother experience; this is the default for new WSL installations on supported hardware. WSL2 requires hardware virtualization support, which is available on most modern CPUs but may require activation in the BIOS/UEFI.
236
+
Instead, we recommend using the [Windows Subsystem for Linux] to run OpenFF software on Windows. WSL runs a Linux kernel within your Windows system so you can run ordinary software as if you had a Linux system. If your hardware supports it, we suggest using WSL2 for a smoother experience; this is the default for new WSL installations on supported hardware. WSL2 requires hardware virtualization support, which is available on most modern CPUs but may require activation in the BIOS/UEFI.
237
237
238
238
In either case, once WSL is installed you can usually follow any documentation as though you had a Linux machine.
239
239
@@ -248,7 +248,7 @@ WSL2 [does support](https://developer.nvidia.com/cuda/wsl) GPU compute, at least
248
248
(install_arm)=
249
249
## OpenFF on Apple Silicon and ARM
250
250
251
-
As of January 2024, OpenFF software and most of its corner of the computational chemistry ecosystem (OpenMM, RDKit, Psi4, etc.) support Apple Silicon (M1, M2, etc.). However, this may not be true if, for example, using old versions of any software. In such cases, we recommend macOS users of Apple Silicon install the x86_64 version of MambaForge and run all OpenFF software through [Rosetta]. ARM systems without access to a similar emulation layer may not be able to access all of the features of OpenFF software.
251
+
As of January 2024, OpenFF software and most of its corner of the computational chemistry ecosystem (OpenMM, RDKit, Psi4, etc.) support Apple Silicon (M1, M2, etc.). However, this may not be true if, for example, using old versions of any software. In such cases, we recommend macOS users of Apple Silicon install the x86_64 version of Miniforge and run all OpenFF software through [Rosetta]. ARM systems without access to a similar emulation layer may not be able to access all of the features of OpenFF software.
252
252
253
253
An existing ARM installation of Conda can be configured to [use Rosetta] with the `CONDA_SUBDIR=osx-64` shell environment variable or the `subdir` Conda config variable. We recommend using this on a per-environment basis so that it persists across updates and new installs, but does not affect existing setups:
0 commit comments