Getting and Installing yt¶
In this document we describe several methods for installing yt. The method that will work best for you depends on your precise situation:
If you do not have root access on your computer, are not comfortable managing python packages, or are working on a machine where you are not allowed to, you will probably want to use the bash all-in-one installation script. This creates a python environment using the miniconda python distribution and the conda package manager inside of a single folder in your home directory. See All-in-One Installation Script for more details.
If you use the Anaconda python distribution and already have
condainstalled, see Installing yt Using Anaconda for details on how to install yt using the
condapackage manager. Note that this is currently the only supported installation mechanism on Windows.
A viable alternative to the installation based on Anaconda is the use of the Intel Distribution for Python. For Parallel Computation on Intel architectures, especially on supercomputers, a large performance and scalability improvement over several common tasks has been demonstrated. Detailed installation instructions are provided below as well, see Using the Intel Distribution for Python from conda. No change in the way yt is managed by
Some operating systems have
ytpre-built packages that can be installed with the system package manager. Note that the packages in some of these distributions may not be the most recent release. See yt Distribution Packages for a list of available packages. You can always get the current stable version of
condaas described in Installing yt Using Anaconda or via
pipas described in Installing yt Using pip.
If you want to build a development version of yt or are comfortable with compilers and know your way around python packaging, Installing yt Using pip will probably be the best choice. If you have set up python using a source-based package manager like Homebrew or MacPorts this choice will let you install yt using the python installed by the package manager. Similarly, this will also work for python environments set up via Linux package managers so long as you have the necessary compilers installed (e.g. the
build-essentialspackage on Debian and Ubuntu).
See Parallel Computation for a discussion on using yt in parallel.
Branches of yt:
Before you install yt, you must decide which branch (i.e. version) of the code you prefer to use:
master– The most up-to-date development version with the most current features but sometimes unstable (the development version of the next release).
stable– The latest stable release of
yt-2.x– The last stable release of
If this is your first time using the code, we recommend using
you specifically need some piece of brand-new functionality only available in
master or need to run an old script developed for
yt-2.x. There were major
API and functionality changes made in yt for version 3.0. For a detailed
description of the changes between versions 2.x (e.g. branch
yt-2.x) and 3.x
stable) see What’s New and Different in yt 3.0?. Lastly, don’t
feel like you’re locked into one branch when you install yt, because you can
easily change the active branch by following the instructions in
Switching versions of yt: yt-2.x, stable, and master branches.
All-in-One Installation Script¶
Because installation of all of the interlocking parts necessary to install yt itself can be time-consuming, yt provides an all-in-one installation script which downloads and builds a fully-isolated installation of Python that includes NumPy, Matplotlib, H5py, git, and yt.
The install script supports UNIX-like systems, including Linux, OS X, and most supercomputer and cluster environments. It is particularly suited for deployment in environments where users do not have root access and can only install software into their home directory.
Since the install is fully-isolated in a single directory, if you get tired of having yt on your system, you can just delete the directory and yt and all of its dependencies will be removed from your system (no scattered files remaining throughout your system).
Running the Install Script¶
You can download the installation script with the following command:
$ wget https://raw.githubusercontent.com/yt-project/yt/master/doc/install_script.sh
If you do not have
wget, the following should also work:
$ curl -OL https://raw.githubusercontent.com/yt-project/yt/master/doc/install_script.sh
By default, the bash install script will create a python environment based on the miniconda python distribution, and will install yt’s dependencies using the conda package manager. To avoid needing a compilation environment to run the install script, yt itself will also be installed using conda.
If you would like to customize your yt installation, you can edit the values of several variables that are defined at the top of the script.
If you would like to build yt from source, you will need to edit the install
script and set
INST_YT_SOURCE=1 near the top. This will clone a copy of the
yt git repository and build yt form source. The default is
INST_YT_SOURCE=0, which installs yt from a binary conda package.
In addition, you can tell the install script to download and install some
additional packages — currently these include
PyX, the Rockstar halo
and the necessary dependencies for
unstructured mesh rendering. The script has
all of the options for installing optional packages near the top of the
file. You should be able to open it and edit it without any knowledge of bash
syntax. For example, to install scipy, change
To execute the install script, run:
$ bash install_script.sh
Because the installer is downloading and building a variety of packages from source, this will likely take a few minutes, especially if you have a slow internet connection. You will get updates of its status at the command prompt throughout.
If you receive errors during this process, the installer will provide you
with a large amount of information to assist in debugging your problems. The
yt_install.log will contain all of the
the entire installation process, so it is usually quite cumbersome. By looking
at the last few hundred lines (i.e.
tail -500 yt_install.log), you can
potentially figure out what went wrong. If you have problems, though, do not
hesitate to contact us for assistance.
Activating Your Installation¶
Once the installation has completed, there will be instructions on how to set up your shell environment to use yt.
In particular, you will need to ensure that the installation’s
directory is prepended to your
PATH environment variable.
For Bash-style shells, you can use the following command in a terminal session to temporarily activate the yt installation:
$ export PATH=/path/to/yt-conda/bin:$PATH
and on csh-style shells:
$ setenv PATH /path/to/yt-conda/bin:$PATH
If you would like to permanently activate yt, you can also update the init file appropriate for your shell and OS (e.g. .bashrc, .bash_profile, .cshrc, .zshrc) to include the same command.
Updating yt and Its Dependencies¶
With many active developers, code development sometimes occurs at a furious pace in yt. To make sure you’re using the latest version of the code, run this command at a command-line:
$ conda update yt
If you want to update your dependencies, run:
$ conda update --all
If you have installed yt from source, you can use the following command to get the latest development version of yt:
$ yt update
Removing yt and Its Dependencies¶
Because yt and its dependencies are installed in an isolated directory when you use the script installer, you can easily remove yt and all of its dependencies cleanly. Simply remove the install directory and its subdirectories:
$ rm -rf yt-conda
If you really had problems with the installation process, this is a last defense for solving: remove and then fully re-install from the install script again.
Installing yt Using Anaconda¶
For both the Anaconda and Miniconda installations, make sure that the Anaconda
bin directory is in your path, and then issue:
$ conda install -c conda-forge yt
which will install stable branch of yt along with all of its dependencies.
Nightly Conda Builds¶
If you would like to install latest development version of yt, you can download it from our custom anaconda channel:
$ conda install -c yt-project/label/dev -c conda-forge yt
New packages for development branch are built after every pull request is merged. In order to make sure you are running latest version, it’s recommended to update frequently:
$ conda update -c yt-project/label/dev -c conda-forge yt
We recommend trying to install dependencies from conda-forge as indicated above
since focused individual communities stand a better chance of successfully
maintaining build recipes. However, if you wish to use the default anaconda
packages, simply remove
-c conda-forge during conda installation.
Location of our channel can be added to
.condarc to avoid retyping it during
each conda invocation. Please refer to Conda Manual
for detailed instructions.
Using the Intel Distribution for Python from conda¶
If you use conda, you can install yt with the Intel Distribution for Python (recommended for performance in parallel computations on Intel architectures) instead of the standard Anaconda distribution. First you need to add the intel channel:
$ conda config --add channels intel
If you want, at this point you can create a separate environment and switch to it:
$ conda create -c intel -n yt_intel $ conda activate yt_intel
Now you need to install the remaining yt dependencies in your current environment. The following provides the Intel-optimized versions of these underlying packages:
$ conda config --add channels intel $ conda install -c intel numpy scipy mpi4py cython git sympy ipython matplotlib netCDF4
Then you can install yt normally, either from the conda-forge channel as above, or from source (see below).
yt Distribution Packages¶
Since the third-party packages listed below are not officially supported by yt developers, support should not be sought out on the project mailing lists or Slack channels. All support requests related to these packages should be directed to their official maintainers.
While we recommended installing
yt with either the
package managers, a number of third-party packages exist for the distributions
listed below. If you can’t find your distro here, you can always install
yt’s current stable version using
pip, or build the latest
development version from source.
Please be aware that the packages in some of these distributions may be out-of-date!
Building yt from Source For Conda-based Installs¶
First, ensure that you have all build dependencies installed in your current conda environment:
$ conda install -c conda-forge cython git sympy ipython matplotlib netCDF4
In addition, you will need a C compiler installed.
Clone the yt repository with:
$ git clone https://github.com/yt-project/yt
Once inside the yt directory, update to the appropriate branch and run
pip install -e .. For example, the following commands will allow
you to see the tip of the development branch.
$ git checkout master $ pip install -e .
This will make sure you are running a version of yt corresponding to the most up-to-date source code.
Alternatively, you can replace
pip install -e . with
conda develop -b ..
Installing Support for the Rockstar Halo Finder¶
The easiest way to set rockstar up in a conda-based python environment is to run
the install script with
If you want to do this manually, you will need to follow these instructions. First, clone Matt Turk’s fork of rockstar and compile it:
$ git clone https://github.com/yt-project/rockstar $ cd rockstar $ make lib
Next, copy librockstar.so into the lib folder of your anaconda installation:
$ cp librockstar.so /path/to/anaconda/lib
Finally, you will need to recompile yt to enable the rockstar interface. Clone a copy of the yt git repository (see Building yt from Source For Conda-based Installs), or navigate to a clone that you have already made, and do the following:
$ cd /path/to/yt-git $ ./clean.sh $ echo /path/to/rockstar > rockstar.cfg $ pip install -e .
/path/to/yt-git is the path to your clone of the yt git repository
/path/to/rockstar is the path to your clone of Matt Turk’s fork of
Finally, to actually use rockstar, you will need to ensure the folder containing librockstar.so is in your LD_LIBRARY_PATH:
$ export LD_LIBRARY_PATH=/path/to/anaconda/lib
You should now be able to enter a python session and import the rockstar interface:
>>> from yt.analysis_modules.halo_finding.rockstar import rockstar_interface
If this python import fails, then you have not installed rockstar and yt’s rockstar interface correctly.
Installing yt Using
If you already have a python installation that you manage using
pip you can
install the latest release of yt by doing:
$ pip install yt
If you do not have root access you may need to append
--user to install to a
location in your home folder.
Installing yt from source¶
If you wish to install yt from source in a conda-based installation of yt, see Building yt from Source For Conda-based Installs.
To install yt from source, you must make sure you have yt’s dependencies installed on your system. Right now, the dependencies to build yt from source include:
A C compiler such as
Python >= 3.5
In addition, building yt from source requires
which can be installed with
$ pip install numpy cython
You may also want to install some of yt’s optional dependencies, including
h5py (which in turn depends on the HDF5 library),
The source code for yt may be found on GitHub. If you prefer to install the
development version of yt instead of the latest stable release, you will need
git to clone the official repo:
$ git clone https://github.com/yt-project/yt $ cd yt $ git checkout master $ pip install . --user --install-option="--prefix="
If you maintain your own user-level python installation separate from the
OS-level python installation, you can leave off
--user --install-option="--prefix=", although
you might need
sudo depending on where python is installed. See This
if you are curious why
--install-option="--prefix=" is necessary on some systems.
This will install yt into a folder in your home directory
$HOME/.local/lib64/python2.7/site-packages on Linux,
$HOME/Library/Python/2.7/lib/python/site-packages/ on OSX) Please refer to
setuptools documentation for the additional options.
If you are unable to locate the
yt executable (i.e. executing
at the bash command line fails), then you likely need to add the
$HOME/.local/bin (or the equivalent on your OS) to your PATH. Some Linux
distributions do not include this directory in the default search path.
If you choose this installation method, you do not need to run any activation script since this will install yt into your global python environment.
If you will be modifying yt, you can also make the clone of the yt git repository the “active” installed copy:
$ git clone https://github.com/yt-project/yt $ cd yt $ git checkout master $ pip install -e . --user --install-option="--prefix="
As above, you can leave off
--user --install-option="--prefix=" if you want to install yt into
the default package install path. If you do not have write access for this
location, you might need to use
Build errors with
Building yt requires version 18.0 or higher of
setuptools. If you see error
messages about this package, you may need to update it. For example, with pip
$ pip install --upgrade setuptools
or your preferred method. If you have
distribute installed, you may also see
error messages for it if it’s out of date. You can update with pip via
$ pip install --upgrade distribute
or via your preferred method.
Keeping yt Updated via Git¶
If you want to maintain your yt installation via updates straight from the GitHub repository or if you want to do some development on your own, we suggest you check out some of the development docs, especially the sections on Git and building yt from source.
You can also make use of the following command to keep yt up to date from the command line:
$ yt update
This will detect that you have installed yt from the git repository, pull any changes from GitHub, and then recompile yt if necessary.
Testing Your Installation¶
To test to make sure everything is installed properly, try running yt at the command line:
$ yt --help
If this works, you should get a list of the various command-line options for yt, which means you have successfully installed yt. Congratulations!
If you like, this might be a good time to run the test suite, see Testing for more details.
Switching versions of yt:
Here we explain how to switch between different development branches of yt.
If You Installed yt Using the Bash Install Script¶
The instructions for how to switch between branches depend on whether you ran
the install script with
INST_YT_SOURCE=0 (the default) or
INST_YT_SOURCE=1. You can determine which option you used by inspecting the
$ yt version
If the output from this command looks like:
The current version and changeset for the code is: --- Version = 3.2.3 ---
i.e. it does not refer to a specific changeset hash, then you originally chose
On the other hand, if the output from
yt version looks like:
The current version and changeset for the code is: --- Version = 3.3-dev Changeset = d8eec89b2c86 ---
i.e. it refers to a specific changeset in the yt git repository, then
you installed using
Conda-based installs (
In this case you can either install one of the nightly conda builds (see Nightly Conda Builds), or you can follow the instructions above to build yt from source under conda (see Building yt from Source For Conda-based Installs).
Source-based installs (
You already have the git repository, so you simply need to switch which version you’re using. Navigate to the root of the yt git repository, check out the desired version, and rebuild the source (some of the C code requires a compilation step for big changes like this):
$ cd yt-<machine>/src/yt-git $ git checkout <desired version> $ pip install -e .
Valid versions to jump to are described in Branches of yt: master, stable, and yt-2.x.
You can check which version of yt you have installed by invoking
at the command line. If you encounter problems, see Update errors.
If You Installed yt Using from Source or Using pip¶
If you have installed python via
any extant installations of yt on your system and clone the git
repository of yt as described in Installing yt Using pip.
$ pip uninstall yt $ git clone https://github.com/yt-project/yt
Now, to switch between versions, you need to navigate to the root of the git yt repository. Use git to update to the appropriate version and recompile.
$ cd yt $ git checkout <desired-version> $ pip install . --user --install-option="--prefix="
Valid versions to jump to are described in Branches of yt: master, stable, and yt-2.x).
You can check which version of yt you have installed by invoking
at the command line. If you encounter problems, see Update errors.