# Installation¶

## Dependencies¶

galpy requires the numpy, scipy, and matplotlib packages; these must be installed or the code will not be able to be imported. The installation methods described below will all automatically install these required dependencies.

Optional dependencies are:

• astropy for Quantity support (used throughout galpy when installed),
• astroquery for the Orbit.from_name initialization method (to initialize using a celestial object’s name),
• tqdm for displaying a progress bar for certain operations (e.g., orbit integration of multiple objects at once)
• numexpr for plotting arbitrary expressions of Orbit quantities,
• numba for speeding up the evaluation of certain functions when using C orbit integration,
• JAX for use of constant-anisotropy DFs in galpy.df.constantbetadf, and
• pynbody for use of SnapshotRZPotential and InterpSnapshotRZPotential.

To be able to use the fast C extensions for orbit integration and action-angle calculations, the GNU Scientific Library (GSL) needs to be installed (see below).

## With conda¶

The easiest way to install the latest released version of galpy is using conda or pip (see below):

conda install galpy -c conda-forge


or:

conda config --add channels conda-forge
conda install galpy


Installing with conda will automatically install the required dependencies (numpy, scipy, and matplotlib) and the GSL, but not the optional dependencies.

## With pip¶

galpy can also be installed using pip. Since v1.6.0, the pip installation will install binary wheels for most major operating systems (Mac, Windows, and Linux) and commonly-used Python 3 versions. When this is the case, you do not need to separately install the GSL.

When you are on a platform or Python version for which no binary wheel is available, pip will compile the source code on your machine. Some advanced features require the GNU Scientific Library (GSL; see below). If you want to use these with a pip-from-source install, install the GSL first (or install it later and re-install using the upgrade command. Then do:

pip install galpy


pip install -U --no-deps galpy


Installing with pip will automatically install the required dependencies (numpy, scipy, and matplotlib), but not the optional dependencies. On a Mac/UNIX system, you can make sure to include the necessary GSL environment variables by doing (see below):

export CFLAGS="$CFLAGS -Igsl-config --prefix/include" && export LDFLAGS="$LDFLAGS -Lgsl-config --prefix/lib" && pip install galpy


The latest updates in galpy can be installed using:

pip install -U --no-deps git+https://github.com/jobovy/galpy.git#egg=galpy


or:

pip install -U --no-deps --prefix=~/local git+https://github.com/jobovy/galpy.git#egg=galpy


for a local installation. The latest updates can also be installed from the source code downloaded from github:

pip install .


or:

pip install --prefix=~/local .


for a local installation.

Note that these latest-version commands all install directly from the source code and thus require you to have the GSL and a C compiler installed to build the C extension(s). If you are having issues with this, you can also download a binary wheel for the latest main version, which are available here. To install these wheels, download the relevant version for your operating system and Python version and do:

pip install WHEEL_FILE.whl


Note that there is also a Pure Python wheel available there, but use of this is not recommended. These wheels have stable ...latest... names, so you can embed them in workflows that should always be using the latest version of galpy (e.g., to test your code against the latest development version).

## Installing from a branch¶

If you want to use a feature that is currently only available in a branch, do:

pip install -U --no-deps git+https://github.com/jobovy/galpy.git@dev#egg=galpy


to, for example, install the dev branch.

Note that we currently do not build binary wheels for branches other than main. If you really wanted this, you could fork galpy, edit the GitHub Actions workflow file that generates the wheel to include the branch that you want to build (in the on: section), and push to GitHub; then the binary wheel will be built as part of your fork. Alternatively, you could do a pull request, which would also trigger the building of the wheels.

## Installing from source on Windows¶

Tip

You can install a pre-compiled Windows “wheel” of the latest main version that is automatically built using GitHub Actions for all recent Python versions here. Download the wheel for your version of Python, and install with pip install WHEEL_FILE.whl (see above).

Versions >1.3 should be able to be compiled on Windows systems using the Microsoft Visual Studio C compiler (>= 2015). For this you need to first install the GNU Scientific Library (GSL), for example using Anaconda (see below). Similar to on a UNIX system, you need to set paths to the header and library files where the GSL is located. On Windows, using the CDM commandline, this is done as:

set INCLUDE=%CONDA_PREFIX%\Library\include;%INCLUDE%
set LIB=%CONDA_PREFIX%\Library\lib;%LIB%
set LIBPATH=%CONDA_PREFIX%\Library\lib;%LIBPATH%


If you are using the Windows PowerShell (which newer versions of the Anaconda prompt might set as the default), do:

$env:INCLUDE="$env:CONDA_PREFIX\Library\include"
$env:LIB="$env:CONDA_PREFIX\Library\lib"
$env:LIBPATH="$env:CONDA_PREFIX\Library\lib"


where in this example CONDA_PREFIX is the path of your current conda environment (the path that ends in \ENV_NAME). If you have installed the GSL somewhere else, adjust these paths (but do not use YOUR_PATH\include\gsl or YOUR_PATH\lib\gsl as the paths, simply use YOUR_PATH\include and YOUR_PATH\lib).

To compile with OpenMP on Windows, you have to install Intel OpenMP via:

conda install -c anaconda intel-openmp


and then to compile the code:

pip install .


If you encounter any issue related to OpenMP during compilation, you can do:

pip install . --install-option="--no-openmp"


Note that in this case, you should install all dependencies (e.g., numpy, scipy, matplotlib) first using conda or pip, because using --install-option causes pip to build all dependencies from source, which may cause problems.

## Installing from source with Intel Compiler¶

Compiling galpy with an Intel Compiler can give significant performance improvements on 64-bit Intel CPUs. Moreover students can obtain a free copy of an Intel Compiler at this link.

To compile the galpy C extensions with the Intel Compiler on 64bit MacOS/Linux do:

python setup.py build_ext --inplace --compiler=intelem


and to compile the galpy C extensions with the Intel Compiler on 64bit Windows do:

python setup.py build_ext --inplace --compiler=intel64w


Then you can simply install with:

python setup.py install


or other similar installation commands.

## Installing the TorusMapper code¶

Warning

The TorusMapper code is not part of any of galpy’s binary distributions (installed using conda or pip); if you want to gain access to the TorusMapper, you need to install from source as explained in this section and above.

Since v1.2, galpy contains a basic interface to the TorusMapper code of Binney & McMillan (2016). This interface uses a stripped-down version of the TorusMapper code, that is not bundled with the galpy code, but kept in a fork of the original TorusMapper code. Installation of the TorusMapper interface is therefore only possible when installing from source after downloading or cloning the galpy code and using the pip install . method above.

To install the TorusMapper code, before running the installation of galpy, navigate to the top-level galpy directory (which contains the setup.py file) and do:

git clone https://github.com/jobovy/Torus.git galpy/actionAngle/actionAngleTorus_c_ext/torus
cd galpy/actionAngle/actionAngleTorus_c_ext/torus
git checkout galpy
cd -


Then proceed to install galpy using the pip install . technique or its variants as usual.

## NEW IN v1.8 Using galpy in web applications¶

galpy can be compiled to WebAssembly using the emscripten compiler. In particular, galpy is part of the pyodide Python distribution for the browser, meaning that galpy can be used on websites without user installation and it still runs at the speed of a compiled language. This powers, for example, the Try galpy interactive session on this documentation’s home page. Thus, it is easy to, e.g., build web-based, interactive galactic-dynamics examples or tutorials without requiring users to install the scientific Python stack and galpy itself.

galpy will be included in versions >0.20 of pyodide, so galpy can be imported in any web context that uses pyodide (e.g., jupyterlite or pyscript). Python packages used in pyodide are compiled to the usual wheels, but for the emscripten compiler. Such a wheel for the latest development version of galpy is always available at galpy-latest-cp310-cp310-emscripten_wasm32.whl (note that this URL will change for future pyodide versions, which include emscripten version numbers in the wheel name). It can be used in pyodide for example as

>>> import pyodide_js
'future','setuptools',
'https://www.galpy.org/wheelhouse/galpy-latest-cp310-cp310-emscripten_wasm32.whl'])


after which you can import galpy and do (almost) everything you can in the Python version of galpy (everything except for querying Simbad using Orbit.from_name and except for Orbit.animate). Note that depending on your context, you might have to just import pyodide to get the loadPackage function.

## Installation FAQ¶

### What is the required numpy version?¶

galpy should mostly work for any relatively recent version of numpy, but some advanced features, including calculating the normalization of certain distribution functions using Gauss-Legendre integration require numpy version 1.7.0 or higher.

### I get warnings like “galpyWarning: libgalpy C extension module not loaded, because libgalpy.so image was not found”¶

This typically means that the GNU Scientific Library (GSL) was unavailable during galpy’s installation, causing the C extensions not to be compiled. Most of the galpy code will still run, but slower because it will run in pure Python. The code requires GSL versions >= 1.14. If you believe that the correct GSL version is installed for galpy, check that the library can be found during installation (see below).

### I get the warning “galpyWarning: libgalpy_actionAngleTorus C extension module not loaded, because libgalpy_actionAngleTorus.so image was not found”¶

This is typically because the TorusMapper code was not compiled, because it was unavailable during installation. This code is only necessary if you want to use galpy.actionAngle.actionAngleTorus. See above for instructions on how to install the TorusMapper code. Note that in recent versions of galpy, you should not be getting this warning, unless you set verbose=True in the configuration file.

### How do I install the GSL?¶

Certain advanced features require the GNU Scientific Library (GSL), with action calculations requiring version 1.14 or higher. The easiest way to install this is using its Anaconda build:

conda install -c conda-forge gsl


If you do not want to go that route, on a Mac, the next easiest way to install the GSL is using Homebrew as:

brew install gsl --universal


You should be able to check your version using (on Mac/Linux):

gsl-config --version


On Linux distributions with apt-get, the GSL can be installed using:

apt-get install libgsl0-dev


or on distros with yum, do:

yum install gsl-devel


On Windows, using conda-forge to install the GSL is your best bet, but note that this doesn’t mean that you have to use conda for the rest of your Python environment. You can simply use a conda environment for the GSL, while using pip to install galpy and other packages. However, in that case, you need to add the relevant conda environment to your PATH. So, for example, you can install the GSL as:

conda create -n gsl gsl
conda activate gsl


and then set the path using: