1************ 2Installation 3************ 4 5Installing ``astropy`` 6====================== 7 8If you are new to Python and/or do not have familiarity with `Python virtual 9environments <https://docs.python.org/3/tutorial/venv.html>`_, then we recommend 10starting by installing the `Anaconda Distribution 11<https://www.anaconda.com/distribution/>`_. This works on all platforms (linux, 12Mac, Windows) and installs a full-featured scientific Python in a user directory 13without requiring root permissions. 14 15Using pip 16--------- 17 18.. warning:: 19 20 Users of the Anaconda Python distribution should follow the instructions 21 for :ref:`anaconda_install`. 22 23To install ``astropy`` with `pip`_, run:: 24 25 pip install astropy 26 27If you want to make sure none of your existing dependencies get upgraded, you 28can also do:: 29 30 pip install astropy --no-deps 31 32On the other hand, if you want to install ``astropy`` along with recommended 33or even all of the available optional :ref:`dependencies <astropy-main-req>`, 34you can do:: 35 36 pip install astropy[recommended] 37 38or:: 39 40 pip install astropy[all] 41 42In most cases, this will install a pre-compiled version (called a *wheel*) of 43astropy, but if you are using a very recent version of Python, if a new version 44of astropy has just been released, or if you are building astropy for a platform 45that is not common, astropy will be installed from a source file. Note that in 46this case you will need a C compiler (e.g., ``gcc`` or ``clang``) to be installed 47(see `Building from source`_ below) for the installation to succeed. 48 49If you get a ``PermissionError`` this means that you do not have the required 50administrative access to install new packages to your Python installation. In 51this case you may consider using the ``--user`` option to install the package 52into your home directory. You can read more about how to do this in the `pip 53documentation <https://pip.pypa.io/en/stable/user_guide/#user-installs>`_. 54 55Alternatively, if you intend to do development on other software that uses 56``astropy``, such as an affiliated package, consider installing ``astropy`` 57into a :ref:`virtualenv <astropy-dev:virtual_envs>`. 58 59Do **not** install ``astropy`` or other third-party packages using ``sudo`` 60unless you are fully aware of the risks. 61 62.. _anaconda_install: 63 64Using Conda 65----------- 66 67To install ``astropy`` using conda run:: 68 69 conda install astropy 70 71``astropy`` is installed by default with the `Anaconda Distribution 72<https://www.anaconda.com/distribution/>`_. To update to the latest version run:: 73 74 conda update astropy 75 76There may be a delay of a day or two between when a new version of ``astropy`` 77is released and when a package is available for conda. You can check 78for the list of available versions with ``conda search astropy``. 79 80If you want to install ``astropy`` along with recommended or all of the 81available optional :ref:`dependencies <astropy-main-req>`, you can do:: 82 83 conda install -c conda-forge -c defaults scipy matplotlib 84 85or:: 86 87 conda install -c conda-forge -c defaults scipy matplotlib \ 88 h5py beautifulsoup4 html5lib bleach pandas sortedcontainers \ 89 pytz setuptools mpmath bottleneck jplephem asdf pyarrow 90 91To also be able to run tests (see below) and support :ref:`builddocs` use the 92following. We use ``pip`` for these packages to ensure getting the latest 93releases which are compatible with the latest ``pytest`` and ``sphinx`` releases:: 94 95 pip install pytest-astropy sphinx-astropy 96 97.. warning:: 98 99 Attempting to use `pip <https://pip.pypa.io>`__ to upgrade your installation 100 of ``astropy`` itself may result in a corrupted installation. 101 102.. _testing_installed_astropy: 103 104Testing an Installed ``astropy`` 105-------------------------------- 106 107{% if is_development %} 108 109The easiest way to test if your installed version of ``astropy`` is running 110correctly is to use the :ref:`astropy.test()` function:: 111 112 import astropy 113 astropy.test() 114 115The tests should run and print out any failures, which you can report at 116the `Astropy issue tracker <https://github.com/astropy/astropy/issues>`_. 117 118This way of running the tests may not work if you do it in the ``astropy`` source 119distribution. See :ref:`sourcebuildtest` for how to run the tests from the 120source code directory, or :ref:`running-tests` for more details. 121 122{%else%} 123 124See the :ref:`latest documentation on how to test your installed version of 125astropy <astropy-dev:testing_installed_astropy>`. 126 127{%endif%} 128 129.. _astropy-main-req: 130 131Requirements 132============ 133 134``astropy`` has the following strict requirements: 135 136- `Python`_ |minimum_python_version| or later 137 138- `Numpy`_ |minimum_numpy_version| or later 139 140- `PyERFA`_ |minimum_pyerfa_version| or later 141 142- `PyYAML <https://pyyaml.org>`_ |minimum_pyyaml_version| or later 143 144- `packaging`_ |minimum_packaging_version| or later 145 146``astropy`` also depends on a number of other packages for optional features. 147The following are particularly recommended: 148 149- `scipy`_ |minimum_scipy_version| or later: To power a variety of features 150 in several modules. 151 152- `matplotlib <https://matplotlib.org/>`_ |minimum_matplotlib_version| or later: To provide plotting 153 functionality that `astropy.visualization` enhances. 154 155The further dependencies provide more specific features: 156 157- `h5py <http://www.h5py.org/>`_: To read/write 158 :class:`~astropy.table.Table` objects from/to HDF5 files. 159 160- `BeautifulSoup <https://www.crummy.com/software/BeautifulSoup/>`_: To read 161 :class:`~astropy.table.table.Table` objects from HTML files. 162 163- `html5lib <https://html5lib.readthedocs.io/en/stable/>`_: To read 164 :class:`~astropy.table.table.Table` objects from HTML files using the 165 `pandas <https://pandas.pydata.org/>`_ reader. 166 167- `bleach <https://bleach.readthedocs.io/>`_: Used to sanitize text when 168 disabling HTML escaping in the :class:`~astropy.table.Table` HTML writer. 169 170- `xmllint <http://www.xmlsoft.org/>`_: To validate VOTABLE XML files. 171 This is a command line tool installed outside of Python. 172 173- `pandas <https://pandas.pydata.org/>`_: To convert 174 :class:`~astropy.table.Table` objects from/to pandas DataFrame objects. 175 Version 0.14 or higher is required to use the :ref:`table_io_pandas` 176 I/O functions to read/write :class:`~astropy.table.Table` objects. 177 178- `sortedcontainers <https://pypi.org/project/sortedcontainers/>`_ for faster 179 ``SCEngine`` indexing engine with ``Table``, although this may still be 180 slower in some cases than the default indexing engine. 181 182- `pytz <https://pythonhosted.org/pytz/>`_: To specify and convert between 183 timezones. 184 185- `jplephem <https://pypi.org/project/jplephem/>`_: To retrieve JPL 186 ephemeris of Solar System objects. 187 188- `setuptools <https://setuptools.readthedocs.io>`_: Used for discovery of 189 entry points which are used to insert fitters into `astropy.modeling.fitting`. 190 191- `mpmath <http://mpmath.org/>`_: Used for the 'kraft-burrows-nousek' 192 interval in `~astropy.stats.poisson_conf_interval`. 193 194- `asdf <https://github.com/spacetelescope/asdf>`_ |minimum_asdf_version| or later: Enables the 195 serialization of various Astropy classes into a portable, hierarchical, 196 human-readable representation. 197 198- `bottleneck <https://pypi.org/project/Bottleneck/>`_: Improves the performance 199 of sigma-clipping and other functionality that may require computing 200 statistics on arrays with NaN values. 201 202- `certifi <https://pypi.org/project/certifi/>`_: Useful when downloading 203 files from HTTPS or FTP+TLS sites in case Python is not able to locate 204 up-to-date root CA certificates on your system; this package is usually 205 already included in many Python installations (e.g., as a dependency of 206 the ``requests`` package). 207 208- `pyarrow <https://arrow.apache.org/docs/python/>`_ |minimum_pyarrow_version| or later: 209 To read/write :class:`~astropy.table.Table` objects from/to Parquet files. 210 211However, note that these packages require installation only if those particular 212features are needed. ``astropy`` will import even if these dependencies are not 213installed. 214 215The following packages can optionally be used when testing: 216 217- `pytest-astropy`_: See :ref:`sourcebuildtest` 218 219- `pytest-xdist <https://pypi.org/project/pytest-xdist/>`_: Used for 220 distributed testing. 221 222- `pytest-mpl <https://github.com/matplotlib/pytest-mpl>`_: Used for testing 223 with Matplotlib figures. 224 225- `objgraph <https://mg.pov.lt/objgraph/>`_: Used only in tests to test for reference leaks. 226 227- `IPython`_ |minimum_ipython_version| or later: 228 Used for testing the notebook interface of `~astropy.table.Table`. 229 230- `coverage <https://coverage.readthedocs.io/>`_: Used for code coverage 231 measurements. 232 233- `skyfield <https://rhodesmill.org/skyfield/>`_: Used for testing Solar System 234 coordinates. 235 236- `spgp4 <https://pypi.org/project/sgp4/>`_: Used for testing satellite positions. 237 238- `tox <https://tox.readthedocs.io/en/latest/>`_: Used to automate testing 239 and documentation builds. 240 241Building from Source 242==================== 243 244Prerequisites 245------------- 246 247You will need a compiler suite and the development headers for Python in order 248to build ``astropy``. You do not need to install any other specific build 249dependencies (such as `Cython <https://cython.org/>`_ or 250`jinja2 <https://jinja.palletsprojects.com/en/master/>`_) since these are 251declared in the ``pyproject.toml`` file and will be automatically installed into 252a temporary build environment by pip. 253 254Prerequisites for Linux 255----------------------- 256 257On Linux, using the package manager for your distribution will usually be the 258easiest route to making sure you have the prerequisites to build ``astropy``. In 259order to build from source, you will need the Python development 260package for your Linux distribution, as well as pip. 261 262For Debian/Ubuntu:: 263 264 sudo apt-get install python3-dev python3-numpy-dev python3-setuptools cython3 python3-jinja2 python3-pytest-astropy 265 266For Fedora/RHEL:: 267 268 sudo yum install python3-devel python3-numpy python3-setuptools python3-Cython python3-jinja2 python3-pytest-astropy 269 270.. note:: Building the developer version of ``astropy`` may require 271 newer versions of the above packages than are available in 272 your distribution's repository. If so, you could either try 273 a more up-to-date distribution (such as Debian ``testing``), 274 or install more up-to-date versions of the packages using 275 ``pip`` or ``conda`` in a virtual environment. 276 277Prerequisites for Mac OS X 278-------------------------- 279 280On MacOS X you will need the XCode command line tools which can be installed 281using:: 282 283 xcode-select --install 284 285Follow the onscreen instructions to install the command line tools required. 286Note that you do **not** need to install the full XCode distribution (assuming 287you are using MacOS X 10.9 or later). 288 289The `instructions for building NumPy from source 290<https://numpy.org/doc/stable/user/building.html>`_ are a good 291resource for setting up your environment to build Python packages. 292 293Obtaining the Source Packages 294----------------------------- 295 296Source Packages 297^^^^^^^^^^^^^^^ 298 299The latest stable source package for ``astropy`` can be `downloaded here 300<https://pypi.org/project/astropy>`_. 301 302Development Repository 303^^^^^^^^^^^^^^^^^^^^^^ 304 305The latest development version of ``astropy`` can be cloned from GitHub 306using this command:: 307 308 git clone git://github.com/astropy/astropy.git 309 310If you wish to participate in the development of ``astropy``, see the 311:ref:`developer-docs`. The present document covers only the basics necessary to 312installing ``astropy``. 313 314Building and Installing 315----------------------- 316 317To build and install ``astropy`` (from the root of the source tree):: 318 319 pip install . 320 321If you install in this way and you make changes to the code, you will need to 322re-run the install command for changes to be reflected. Alternatively, you can 323use:: 324 325 pip install -e . 326 327which installs ``astropy`` in develop/editable mode -- this then means that 328changes in the code are immediately reflected in the installed version. 329 330Troubleshooting 331--------------- 332 333If you get an error mentioning that you do not have the correct permissions to 334install ``astropy`` into the default ``site-packages`` directory, you can try 335installing with:: 336 337 pip install . --user 338 339which will install into a default directory in your home directory. 340 341.. _external_c_libraries: 342 343External C Libraries 344^^^^^^^^^^^^^^^^^^^^ 345 346The ``astropy`` source ships with the C source code of a number of 347libraries. By default, these internal copies are used to build 348``astropy``. However, if you wish to use the system-wide installation of 349one of those libraries, you can set environment variables with the 350pattern ``ASTROPY_USE_SYSTEM_???`` to ``1`` when building/installing 351the package. 352 353For example, to build ``astropy`` using the system's expat parser 354library, use:: 355 356 ASTROPY_USE_SYSTEM_EXPAT=1 pip install -e . 357 358To build using all of the system libraries, use:: 359 360 ASTROPY_USE_SYSTEM_ALL=1 pip install -e . 361 362The C libraries currently bundled with ``astropy`` include: 363 364- `wcslib <https://www.atnf.csiro.au/people/mcalabre/WCS/>`_ see 365 ``cextern/wcslib/README`` for the bundled version. To use the 366 system version, set ``ASTROPY_USE_SYSTEM_WCSLIB=1``. 367 368- `cfitsio <https://heasarc.gsfc.nasa.gov/fitsio/fitsio.html>`_ see 369 ``cextern/cfitsio/changes.txt`` for the bundled version. To use the 370 system version, set ``ASTROPY_USE_SYSTEM_CFITSIO=1``. 371 372- `expat <https://libexpat.github.io/>`_ see ``cextern/expat/README`` for the 373 bundled version. To use the system version, set ``ASTROPY_USE_SYSTEM_EXPAT=1``. 374 375 376Installing ``astropy`` into CASA 377-------------------------------- 378 379If you want to be able to use ``astropy`` inside `CASA 380<https://casa.nrao.edu/>`_, the easiest way is to do so from inside CASA. 381 382First, we need to make sure `pip <https://pip.pypa.io>`__ is 383installed. Start up CASA as normal, and then type:: 384 385 CASA <2>: from setuptools.command import easy_install 386 387 CASA <3>: easy_install.main(['--user', 'pip']) 388 389Now, quit CASA and re-open it, then type the following to install ``astropy``:: 390 391 CASA <2>: import subprocess, sys 392 393 CASA <3>: subprocess.check_call([sys.executable, '-m', 'pip', 'install', '--user', 'astropy']) 394 395Then close CASA again and open it, and you should be able to import ``astropy``:: 396 397 CASA <2>: import astropy 398 399Any ``astropy`` affiliated package can be installed the same way (e.g. the 400`spectral-cube <https://spectral-cube.readthedocs.io>`_ or other 401packages that may be useful for radio astronomy). 402 403.. note:: The above instructions have not been tested on all systems. 404 We know of a few examples that do work, but that is not a guarantee 405 that this will work on all systems. If you install ``astropy`` and begin to 406 encounter issues with CASA, please look at the `known CASA issues 407 <https://github.com/astropy/astropy/issues?q=+label%3ACASA-Installation+>`_ 408 and if you do not encounter your issue there, please post a new one. 409 410 411Installing pre-built Development Versions of ``astropy`` 412-------------------------------------------------------- 413 414Most nights a development snapshot of ``astropy`` will be compiled. 415This is useful if you want to test against a development version of astropy but 416do not want to have to build it yourselves. You can see the 417`available astropy dev snapshots page <https://dev.azure.com/astropy-project/astropy/_packaging?_a=package&feed=nightly&package=astropy&protocolType=PyPI&view=versions>`_ 418to find out what is currently being offered. 419 420Installing these "nightlies" of ``astropy`` can be achieved by using ``pip``:: 421 422 $ pip install --extra-index-url=https://pkgs.dev.azure.com/astropy-project/astropy/_packaging/nightly/pypi/simple/ --pre astropy 423 424The extra index URL tells ``pip`` to check the ``pip`` index on Azure Pipelines, where the 425nightlies are built, and the ``--pre`` command tells ``pip`` to install pre-release 426versions (in this case ``.dev`` releases). 427 428.. _builddocs: 429 430Building Documentation 431---------------------- 432 433.. note:: 434 435 Building the documentation is in general not necessary unless you are 436 writing new documentation or do not have internet access, because 437 the latest (and archive) versions of Astropy's documentation should 438 be available at `docs.astropy.org <https://docs.astropy.org>`_ . 439 440Dependencies 441^^^^^^^^^^^^ 442 443Building the documentation requires the ``astropy`` source code and some 444additional packages. The easiest way to build the documentation is to use `tox 445<https://tox.readthedocs.io/en/latest/>`_ as detailed in 446:ref:`astropy-doc-building`. If you are happy to do this, you can skip the rest 447of this section. 448 449On the other hand, if you wish to call Sphinx manually to build the 450documentation, you will need to make sure that a number of dependencies are 451installed. If you use conda, the easiest way to install the dependencies is 452with:: 453 454 conda install -c conda-forge sphinx-astropy 455 456Without conda, you install the dependencies by specifying ``[docs]`` when 457installing ``astropy`` with pip:: 458 459 pip install -e '.[docs]' 460 461You can alternatively install the `sphinx-astropy 462<https://github.com/astropy/sphinx-astropy>`_ package with pip:: 463 464 pip install sphinx-astropy 465 466In addition to providing configuration common to packages in the Astropy 467ecosystem, this package also serves as a way to automatically get the main 468dependencies, including: 469 470* `Sphinx <http://www.sphinx-doc.org>`_ - the main package we use to build 471 the documentation 472* `astropy-sphinx-theme <https://github.com/astropy/astropy-sphinx-theme>`_ - 473 the default 'bootstrap' theme used by ``astropy`` and a number of affiliated 474 packages 475* `sphinx-automodapi <https://sphinx-automodapi.readthedocs.io>`_ - an extension 476 that makes it easy to automatically generate API documentation 477* `sphinx-gallery <https://sphinx-gallery.readthedocs.io/en/latest/>`_ - an 478 extension to generate example galleries 479* `numpydoc`_ - an extension to parse 480 docstrings in NumPyDoc format 481* `pillow <https://pillow.readthedocs.io>`_ - used in one of the examples 482* `Graphviz <http://www.graphviz.org>`_ - generate inheritance graphs (available 483 as a conda package or a system install but not in pip) 484 485.. Note:: 486 Both of the ``pip`` install methods above do not include `Graphviz 487 <http://www.graphviz.org>`_. If you do not install this package separately 488 then the documentation build process will produce a very large number of 489 lengthy warnings (which can obscure bona fide warnings) and also not 490 generate inheritance graphs. 491 492.. _astropy-doc-building: 493 494Building 495^^^^^^^^ 496 497There are two ways to build the Astropy documentation. The easiest way is to 498execute the following tox command (from the ``astropy`` source directory):: 499 500 tox -e build_docs 501 502If you do this, you do not need to install any of the documentation dependencies 503as this will be done automatically. The documentation will be built in the 504``docs/_build/html`` directory, and can be read by pointing a web browser to 505``docs/_build/html/index.html``. 506 507Alternatively, you can do:: 508 509 cd docs 510 make html 511 512And the documentation will be generated in the same location. Note that 513this uses the installed version of astropy, so if you want to make sure 514the current repository version is used, you will need to install it with 515e.g.:: 516 517 pip install -e .[docs] 518 519before changing to the ``docs`` directory. 520 521In the second way, LaTeX documentation can be generated by using the command:: 522 523 make latex 524 525The LaTeX file ``Astropy.tex`` will be created in the ``docs/_build/latex`` 526directory, and can be compiled using ``pdflatex``. 527 528Reporting Issues/Requesting Features 529^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 530 531As mentioned above, building the documentation depends on a number of Sphinx 532extensions and other packages. Since it is not always possible to know which 533package is causing issues or would need to have a new feature implemented, you 534can open an issue in the `core astropy package issue 535tracker <https://github.com/astropy/astropy/issues>`_. However, if you wish, you 536can also open issues in the repositories for some of the dependencies: 537 538* For requests/issues related to the appearance of the docs (e.g. related to 539 the CSS), you can open an issue in the `astropy-sphinx-theme issue tracker 540 <https://github.com/astropy/astropy-sphinx-theme/issues>`_. 541 542* For requests/issues related to the auto-generated API docs which appear to 543 be general issues rather than an issue with a specific docstring, you can use 544 the `sphinx-automodapi issue tracker 545 <https://github.com/astropy/sphinx-automodapi/issues>`_. 546 547* For issues related to the default configuration (e.g which extensions are 548 enabled by default), you can use the `sphinx-astropy issue tracker 549 <https://github.com/astropy/sphinx-astropy/issues>`_. 550 551.. _sourcebuildtest: 552 553Testing a Source Code Build of ``astropy`` 554------------------------------------------ 555 556{% if is_development %} 557 558The easiest way to run the tests in a source checkout of ``astropy`` 559is to use `tox <https://tox.readthedocs.io/en/latest/>`_:: 560 561 tox -e test-alldeps 562 563There are also alternative methods of :ref:`running-tests` if you 564would like more control over the testing process. 565 566{%else%} 567 568See the :ref:`latest documentation on how to run the tests in a source 569checkout of astropy <astropy-dev:sourcebuildtest>` 570 571{%endif%} 572