To run all the workshop notebooks on your own computer, please be sure your machine is configured with the packages in the installation check file. These packages are the ones we use to verify that the notebooks are working as expected.
These instructions describe setup using git and Miniconda. It is not strictly necessary
to use either of these. See the section
Alternate Installation Methods at the end
of this document.
If you have any problems with any of these steps, please check if your problem has already been reported at the issue tracker. If not, ask your question in the issue tracker. You can also [join Astropy Slack] and ask on the #workshops channel.
For the commands shown, % (and anything to the left of it) represents the
terminal prompt. You do not need to copy it; instead only copy the command to the
right of %.
If you are using Windows, we now recommend using the Windows Subsystem for Linux (WSL) instead of using native Windows tools. WSL is now fully supported by Microsoft and tends to result in fewer install headaches, and lets you use tools that were developed for Linux seemlessly in windows. While you still may be able to use the Windows-native installation of Miniforge, these instructions focus on the WSL approach for the above reasons.
To install WSL, you should follow the instructions Microsoft provides here: https://docs.microsoft.com/en-us/windows/wsl/install. While you may choose an alternative Linux distribution from the default Ubuntu, the instructions below have been tested on Ubuntu, so unless you have a specific reason, we suggest you stick with the default. Once you reach the point in the instructions with a working Linux terminal prompt, you can proceed to step 1 of these instructions.
Optional While you can run a WSL terminal with the command prompt built into Windows, it's rather bare-bones and you may not have the best experience. For WSL on Windows you'll probably want to install Windows Terminal to have a terminal experience closer to what you'd see on Mac or Linux.
Miniforge is a free minimal installer for conda. It is a small, bootstrap version of Anaconda that includes only conda, Python, the packages they depend on, and a small number of other useful packages, including pip, zlib and a few others. It also defaults to using the conda-forge service to get packages, which has the widest set of packages and has all freely-licensed software (unlike Anaconda or miniconda). Note, though, that if you have either Miniforge, miniconda, or the full Anaconda already installed, you can skip to the next step.
In a terminal window, check if Miniforge or another conda-like installer is already installed.
% conda info
If a conda is not already installed, follow these instructions for your operating system: https://github.com/conda-forge/miniforge/blob/main/README.md . Please be sure to install a 64-bit version of Miniforge to ensure all packages work correctly.
(On native Windows, you might also need additional compilers, although this should not be necessary in WSL).
Miniforge includes an environment manager called conda. Environments
allow you to have multiple sets of Python packages installed at the same
time, making reproducibility and upgrades easier. You can create,
export, list, remove, and update environments that have different versions of
Python and/or packages installed in them. For this workshop, we will configure the
environment using the conda command prompt.
Open a terminal window and verify that conda is working:
% conda info
If you are having trouble, check your shell in a terminal window:
% echo $SHELL
then run the initialization if needed, in that same terminal window:
% conda init `basename $SHELL`
You should open a new terminal window after conda init is run.
It is advisable to update your conda to the latest version. We recommend a minimum version of 23.10.0. Check your conda version with:
% conda --version
Update it with:
% conda update conda
or
% conda update -n base conda
At the prompt opened in the previous step, enter this command to see whether git is already installed and accessible to this shell:
% git --version
If the output shows a git version, proceed to the next step. Otherwise install git by entering the following command and following the prompts:
% conda install git
If using git, clone the workshop repository using
git:
% git clone https://github.com/astropy/astropy-workshop
Next, check out the version of the workshop we are using for these workshops (updated late on Dec 1):
% git checkout -b ALOHA-2024 origin/ALOHA-2024
If you elect not to use git, you can download the ZIP file using this link: https://github.com/astropy/astropy-workshop/archive/refs/heads/ALOHA-2024.zip
Miniforge includes an environment manager called conda. Environments
allow you to have multiple sets of Python packages installed at the same
time, making reproducibility and upgrades easier. You can create,
export, list, remove, and update environments that have different versions of
Python and/or packages installed in them.
Create a conda environment for this workshop using a yml file.
The python version is specified in the
environment.yml file.
Open a terminal window using the appropriate one for your operating system.
Now navigate to this directory in the terminal. For example, if you installed the astropy-workshop directory in your home directory, you could type the following.
% cd astropy-workshop/00-Install_and_Setup/
And finally, on any platform, to install and activate the astropy-workshop environment, type:
% conda env create --file environment.yml
% conda activate astropy-env
Note, you will need conda version 23.10.0 and later. If you need to update your version use conda update conda.
The name of the new conda environment created above should be displayed next
to the terminal prompt: (astropy-env) %
All the required packages are specified in the requirements.txt file. Install them with:
(astropy-env) % pip install -r requirements.txt
The name of the new conda environment created above should be displayed next
to the terminal prompt: (astropy-env) %
In the terminal you used in the preceding step, inside the astropy-workshop/00_Install_and_Setup/
directory, run the check_env.py script to
check the Python environment and some of the required dependencies:
(astropy-env) % python check_env.py
If the script reports that some of the versions do not match, check first
whether the package was installed using conda or pip, then update accordingly.
The example below a fake package called packagename; replace it with the
actual package that you need to update.
(astropy-env) % conda list packagename
If it was installed with conda, you will see (the channel column might or might not be populated):
# packages in environment at .../miniforge/envs/astropy-env:
#
# Name Version Build Channel
packagename X.Y.Z py37hf484d3e_1000
Otherwise, if it was installed with pip, you will see the channel stating the
name pypi:
# packages in environment at .../miniforge/envs/astropy-env:
#
# Name Version Build Channel
packagename X.Y.Z pypi_0 pypi
To update the reported package with conda:
(astropy-env) % conda update packagename -c conda-forge
Otherwise, to update with pip:
(astropy-env) % pip install packagename --upgrade
The exception to this is if the astroquery package is reported as
out-of-date, always update to its pre-release version with pip:
(astropy-env) % pip install astroquery --pre --upgrade
In the terminal window you used with the conda environment created above,
change directory to the top level astropy_workshop directory.
(astropy-env) % cd ..
Make sure the current directory in your terminal contains all the numbered notebook directories. Then start Jupyter Lab:
(astropy-env) % jupyter lab
If successful, your browser would open a new page/tab pointing to
localhost and show you a listing of the directory including all the numbered
notebook subdirectories.
Click into one of the notebook directories such as 02-PythonIntro.
Double-click on a notebook such as 01. Numbers, String, and Lists.ipynb
and wait for it to launch. On the top right corner,
if you see a blue "Kernel Ready" message appear and disappear,
then all is well. However, if you see a red "Kernel Error," click on it
and scroll down to see the error message. If it says FileNotFoundError,
shut down the notebook server on your terminal and run this command:
(astropy-env) % python -m ipykernel install --user
Now, try run jupyter lab again as above, and the "Kernel Error"
should be gone. Just to be sure, run the first cell (usually an import)
and see if it is successful.
Furthermore, to ensure that the notebook is picking up astropy from
the correct environment, create a new cell in the notebook (use the +
button in the top menu) and run the following code:
import astropy
print(astropy.__version__)
If the reported astropy version is older than expected and you have
not run the python -m ipykernel install --user command, then run it
as instructed above.
Although we recommend Miniforge, you can use pip install -r requirements.txt
into an existing Python installation, or create a virtual environment using
pip/venv.