To install Halotools, you can use conda-forge (recommended), pip, or clone the repo from GitHub and build the source code. Either way, be sure to read the Dependencies section prior to installation.
Using conda-forge and pip¶
The simplest and most reliable way to install the latest release of the code is with conda-forge. If you will be Installing Halotools using a virtual environment, activate the environment before installing:
conda install -c conda-forge halotools
Pip installation is not recommended because the conda-forge dependency solver is much more robust. However, users who prefer pip can install via:
pip install halotools
Either pip or conda will install the latest official release of the code.
If instead you want the latest master branch, you will need to build the code from source following the instructions in the next section.
Consider installing Halotools into a virtual environment. Setting this up is completely straightforward and takes less than a minute, even if this is your first time using a virtual environment. Using a virtual environment simplifies not just the current installation but also package upgrades and your subsequent workflow. If you use conda to manage your python distribution, you can find explicit instructions in the Installing Halotools using a virtual environment section of the documentation.
Building from source¶
If you don’t install the latest release using conda or pip, you can instead clone the cource code and call the setup file. This is the most common way to install Halotools if you want versions of the code that have been updated since the latest official release. In this case, after installation it is particularly important that you follow the instructions in the Verifying your installation section below.
Before installation, be sure you have installed the package dependencies described in the Dependencies section. If you will be Installing Halotools using a virtual environment, activate the environment before following the instructions below. The first step is to clone the halotools repository:
git clone https://github.com/astropy/halotools.git cd halotools
Installing one of the official releases¶
All official releases of the code are tagged with their version name, e.g., v0.7. To install a particular release:
git checkout v0.7 pip install .
This will install the v0.7 release of the code. Other official release versions (e.g., v0.5) can be installed similarly.
Installing the most recent master branch¶
If you prefer to use the most recent version of the code:
git checkout master pip install .
This will install the master branch of the code that is currently under development. While the features in the official releases have a stable API, new features being developed in the master branch may not. However, the master branch may have new features and/or performance enhancements that you may wish to use for your science application. A concerted effort is made to ensure that only thoroughly tested and documented code appears in the public master branch, though Halotools users should be aware of the distinction between the bleeding edge version in master and the official release version available through pip.
Optional: If you need to fine-tune the optimization of an especially
performance-critical science application,
we recommend that you install the package from source.
This will give you the opportunity to manually
throw your own compiler flags that are enabled by
your version of gcc. For example, throwing the
can improve performance of the
functions by 10-40% (with zero impact on the performance
of the mock-making algorithm implemented in
To compile Halotools with these flags thrown,
simply add two new elements to the
extra_compiler_args list in every source code file
setup_package.py: the string
When you’ve made these modifications to the code,
install Halotools by following the Building fom source instructions above
using with your locally modified source code.
Alternatively, if you have an older version of gcc that
does not support the default choice for these flags made by Halotools,
you may need to remove the flag causing the installation problem.
If you install halotools using conda or pip, then most of your dependencies will be handled for you automatically. The only additional dependency you may need is:
h5py: 3.7 or later
The h5py package is used for fast I/O of large simulated datasets.
If you did not use conda or pip, then you should be aware of the following strict requirements:
Numpy: 1.9 or later
Scipy: 0.15 or later
Cython: 0.29.32 or later
Astropy: 5.0 or later
BeautifulSoup: For crawling the web for halo catalogs.
Requests: Also for crawling the web for halo catalogs.
Any of the above can be installed with either pip or conda.
Verifying your installation¶
After installing the code and its dependencies, start up a Python interpreter and check that the version number matches what you expect:
import halotools print(halotools.__version__)
If the version number is not what it should be, this likely means you have a previous
installation that is superseding the version you tried to install. This should be accomplished by doing
conda remove halotools before your new installation, but you may need to uninstall the previous build “manually”. Like all python packages, you can find the installation location as follows:
import halotools print(halotools.__file__)
This will show where your active version is located on your machine. You can manually delete this copy of Halotools prior to your new installation to avoid version conflicts. (There may be multiple copies of Halotools in this location, depending on how may times you have previously installed the code - all such copies may be deleted prior to reinstallation).
Once you have installed the package, see Getting started with Halotools for instructions on how to get up and running.
Testing your installation¶
To verify that your Halotools installation runs properly, navigate to some new working directory and execute the test suite. If you installed Halotools into a virtual environment as described in the Installing Halotools using a virtual environment section of the documentation, activate the environment before spawning a python session and executing the code below.
For halotools versions v0.6 and later, there is a
test_installation feature that runs a few simple tests scattered throughout the code base:
import halotools halotools.test_installation() # v0.6 and later
For earlier versions, you will need to run the full test suite, which is more memory intensive and takes several minutes to run:
halotools.test() # v0.5 and earlier
Whether you installed the master branch or a release branch, the message that concludes the execution of the test suite should not indicate that there were any errors or failures. A typical acceptable test suite report will read something like “445 passed, 45 skipped in 383.2 seconds”. If you installed the master branch, your message may read something like “475 passed, 4 xfailed in 374.3 seconds”. The xfail marker is shorthand for “expected failure”; tests marked by xfail do not indicate a bug or installation problem; instead, this indicates that there is a new feature that has only been partially implemented. If you encounter problems when running the test suite, please be sure you have installed the package dependencies first before raising a Github Issue and/or contacting the Halotools developers.
See Installation Troubleshooting for solutions to known installation-related problems.