{ "cells": [ { "cell_type": "markdown", "id": "8c49c459", "metadata": {}, "source": [ ":::{include} ../textbook-header.md\n", ":::\n", "\n", "## What You Need\n", "\n", "You should have **Bash** and the Miniconda distribution of **Python** 3.x setup on your computer and an `earth-analytics` working directory. Be sure you have:\n", "\n", "* Completed the setup for Git, Bash and Conda.\n", "* Created a `earth-analytics` directory on your computer.\n", "\n", "Information below is adapted from materials developed by the Conda documentation for installing conda and managing conda environments. \n", "\n", "\n", "## Why Use Conda Environments for Python\n", "\n", "Conda allows you to have different environments installed on your computer to access different versions of **Python** and different libraries. Sometimes libraries conflict which causes errors and packages not to work. \n", "\n", "To avoid conflicts, we created an environment called `earth-analytics-python` that contains all of the libraries that you will need for the **Earth Analytics Python** course lessons on this website.\n", "\n", ":::{admonition} `conda` resources\n", ":class: data-tip margin\n", "\n", "For a more detailed explanation of conda environments, see the Intro to Earth Data Science textbook page on Using Conda Environments to Manage Python Dependencies.\n", "\n", "You can also check out the documentation on conda environments. \n", ":::\n", "\n", "## Mamba will save you SO much time\n", "\n", "`mamba` is an extension of `conda` that contains all the same commands. It is also *much* faster (~5 minutes to install the `earth-analytics-python environment, instead of ~90 minutes with plain `conda`).\n", "\n", "To install mamba in your base environment:\n", "\n", "1. If it's not already open, open the Terminal on your computer (e.g. Git Bash for Windows or Terminal on a Mac/Linux).\n", "2. Make sure the `base` environment is active. You should see `(base)` in your terminal prompt. If you don't, run `conda activate base`.\n", "3. Install `mamba` with the command `conda install -c conda-forge mamba`.\n", "\n", ":::{admonition} Use the conda-forge channel\n", ":class: warning margin\n", "\n", "When you install individual packages with conda, don't forget to specify `conda-forge` as the channel where applicable (if you're not sure, it probably is). This is one of the most common problems new users run into, since the `default` channel package recipes are less reliable in our experience.\n", ":::\n", "\n", "## Install the Earth Analytics Python Conda Environment\n", "\n", "To install the `earth-analytics-python` environment, you will need to follow these steps: \n", "\n", "1. Fork and clone a GitHub repository from `https://github.com/earthlab/earth-analytics-python-env` to your `earth-analytics` directory. \n", " * This repository contains a file called `environment.yml` that contains the instructions to install the environment.\n", " * For a refresher on forking/cloning repositories, see the section below on **Fork and Clone GitHub Repository** at the bottom of this lesson. \n", "2. If it's not already open, open the Terminal on your computer (e.g. Git Bash for Windows or Terminal on a Mac/Linux).\n", "3. In the Terminal, set your directory to the cloned `earth-analytics-python-env` dir using `cd` to change directories (e.g. `cd earth-analytics-python-env`).\n", "4. Once you are in the `earth-analytics-python-env` directory, you can create your environment. To do this run: `mamba env create -f environment.yml`.\n", " * Once the environment is installed you can activate it using: `conda activate earth-analytics-python`.\n", "5. To view a list of all conda environments available on your machine run: `conda info --envs`.\n", "\n", ":::{error}\n", "**Always make sure that the earth-analytics-python environment is activated** before doing work for lessons on this website. If you are using live coding on this page, we've taken care of that for you already.\n", ":::\n", "\n", "Note that it takes time to install of the packages found in the earth-analytics-python environment as it needs to download and install each library. It should not take as long with `mamba`, however. \n", "\n", ":::{warning} `conda` needs internet access\n", "You need to have internet access to install packages and environments!\n", ":::\n", "\n", ":::{admonition} Check your working directory\n", ":class: warning\n", "\n", "The instructions above will only work if you run them in the directory where you placed the environment.yml file.\n", ":::\n", "\n", ":::{admonition} Windows Users\n", ":class: warning\n", "\n", "A reminder that the lessons on this website assume that you are using Git Bash as your primary terminal. \n", ":::\n", "\n", "\n", "## About Conda Environments\n", "\n", "### What is a YAML (.yml) File?\n", "\n", "When you work with conda, you can create custom lists that tell conda where to install libraries from, and in what order. You can even specify a particular version. \n", "\n", "You write this list using YAML (Yet Another Markup Language). This is an alternative to using `pip` to install **Python** packages. \n", "\n", "In previous steps, you used a custom .yml list to install all of the **Python** libraries that you will need to complete the **Python** lessons on this website. This .yml list is customized to install libraries from the repositories and in an order that minimizes conflicts. \n", "\n", "If you run into any issues installing the environment from the .yml, let us know! \n", "\n", "Next, explore your new conda environment. Here’s what part of the .yml file looks like:\n", "\n", "```{code-block}\n", "name: earth-analytics-python\n", "channels:\n", " - conda-forge\n", " - defaults\n", "\n", "dependencies:\n", " - python=3.10\n", " - pip\n", " # Core scientific python\n", " - numpy\n", " - matplotlib\n", "```\n", "\n", "Notice at the top of the file there is the environment name. This file has a few key parts: \n", "\n", "1. Name: the name of the environment that you will call when you want to activate the environment. The name `earth-analytics-python` is defined in the environment.yml file.\n", "\n", "2. Channels: this list identifies where packages will be installed from. There are many options including conda, conda-forge and pip. You will be predominately using conda-forge for the `earth-analytics-python` environment. \n", "\n", "3. Dependencies: Dependencies are all of the things that you need installed in order for the environment to be complete. In the example, **Python** version 3.7 is specified. The order in which the libraries should be installed is also specified. \n", "\n", "\n", "## Use Conda Environments\n", "\n", "You can have different **Python** environments on your computer. Conda allows you to easily jump between environments using a set of commands that you run in your terminal. \n", "\n", "This section provides an overview of various commands to manage your conda environments. \n", "\n", "For more detailed instructions for using these commands, see the Intro to Earth Data Science textbook page on [Installing Python Packages in Conda Environments](intro-to-earth-data-science/python-code-fundamentals/use-python-packages/use-conda-environments-and-install-packages).\n", "\n", "Or, have a look at the Conda documentation notes that review the steps below and more!\n", "\n", "\n", "### View a List of All Installed Conda Environments\n", "\n", "You can see a list of all installed conda environments by typing:\n", "\n", "```bash\n", "\n", "conda info --envs\n", "\n", "```\n", "\n", "If you want to use a particular environment that you have installed on your computer, you need to activate it. \n", "\n", "For example, if a **Python** package such as `geopandas` is only installed in the `earth-analytics-python` environment, and not the default conda environment, you will not be able to access it (e.g. import it to `Jupyter Notebook`), unless you have the `earth-analytics-python` environment activated.\n", "\n", "\n", "### Activate a Conda Environment\n", "\n", "**To activate an environment**, use the Terminal to navigate to your earth-analytics directory (e.g. `cd` to the directory). Then, type the following command to activate the environment (e.g. `earth-analytics-python`):\n", "\n", "```bash\n", "conda activate earth-analytics-python\n", "``` \n", "\n", "For older installations of conda (versions prior to 4.6) on Mac, Linux, and Git Bash for Windows, type:\n", "\n", "```bash\n", "source activate earth-analytics-python\n", "```\n", ":::{admonition} Windows Users\n", ":class: warning\n", "\n", "The first time that you try to run the \"conda activate\" command, you may be asked to configure Git Bash to use \"conda activate\". You can do this by running the command \"conda init bash\", just one time. After that, Git Bash will be configured to use \"conda activate\" moving forward. \n", ":::\n", "\n", "Once the environment is activated, the name of the activated environment will appear in parentheses on the left side of your terminal (e.g. `(earth-analytics-python`). \n", "\n", ":::{admonition} Always activate your environment\n", ":class: data-tip\n", "\n", "Note that after you restart the Terminal, the `earth-analytics-python` environment is no longer active. You will need to activate the `earth-analytics-python` environment each time you start the Terminal by running the appropriate command provided above for your operating system. \n", ":::\n", "\n", "\n", "### Deactivate a Conda Environment \n", "\n", "If needed, you can deactivate a conda environment. Deactivating the environment switches you back to the default environment in your computer. \n", "\n", "```bash\n", "conda deactivate\n", "\n", "```\n", "\n", "### Delete a Conda Environment\n", "\n", "If you ever want to delete an envrionment, you must first deactivate that environment and then type: \n", "\n", "```bash\n", "conda env remove --name myenv\n", "``` \n", "\n", "and replace `myenv` with the name of the environment that you want to remove. \n", "\n", ":::{error}\n", "**Remember to never delete your root environment.** \n", ":::\n", "\n", "### Update a Conda Environment Using a YAML File\n", "\n", "Once you have created a conda environment, you can update it anytime by first activating the environment and then running the `conda env update` command.\n", "\n", "The example below updates the `earth-analytics-python environment` using the `environment.yml` file. In this example, the command `conda env update` is run in the same directory that contains the `environment.yml` file.\n", "\n", "```bash\n", "$ conda activate earth-analytics-python\n", "$ conda env update -f environment.yml\n", "```\n", "\n", "Running this command will update your current `earth-analytics-python` environment to include the most current versions of the packages listed in that environment file.\n", "\n", ":::{admonition} How to Fork and Clone a GitHub Repository\n", ":class: info\n", "\n", "This section provides the basic steps for forking a **GitHub** repository (i.e. copying an existing repository to your `Github` account) and cloning a forked repository (i.e. downloading your forked repository locally to your computer). \n", "\n", "For a more detailed explanation of these steps, see the Intro to Earth Data Science textbook chapter on Copy (Fork) and Download (Clone) GitHub Repositories.\n", "\n", "**1. Fork a Repository on GitHub.com**\n", "\n", "You can `fork` an existing **GitHub** repository from the main `Github.com` page of the repository that you want to copy (example: `https://github.com/earthlab/earth-analytics-python-env`).\n", "\n", "On the main `Github.com` page of the repository, you will see a button on the top right that says `Fork`. \n", "\n", "Click on the `Fork` button and select your `Github.com` account as the home of the forked repository. \n", "\n", "
\n", " \n", " \"You\n", "
You can create a copy of repositories created by other users on Github by forking their repository to your Github account. \n", "
\n", "
\n", "\n", "\n", "**2. Clone a Repository to Local Computer or JupyterHub**\n", "\n", "To download your forked copy of the `earth-analytics-python-env` repository to your computer, open the Terminal and change directories to your `earth-analytics` directory (e.g. `cd ~`, then `cd earth-analytics`).\n", "\n", "Then, run the command `git clone` followed by the URL to your fork on **GitHub** (e.g. `https://github.com/your-username/earth-analytics-python-env`). Be sure to change `your-username` to your `Github.com` account username. \n", "\n", "```bash\n", "cd ~\n", "cd earth-analytics\n", "git clone https://github.com/your-username/earth-analytics-python-env\n", "```\n", ":::" ] } ], "metadata": { "jupytext": { "formats": "ipynb,md:myst", "text_representation": { "extension": ".md", "format_name": "myst", "format_version": 0.13, "jupytext_version": "1.14.7" } }, "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "myst": { "substitutions": { "authors": "Leah Wasser, Jenny Palomino, Martha Morrissey, Will Norris, Elsa Culler", "excerpt": "Conda environments allow you to easily manage the Python package installations on your computer. Learn how to install a conda environment using a yml file. \n", "objective": "* Install a new environment using conda and mamba.\n* View a list of the available environments in conda.\n* Activate, update and delete conda environments.", "title": "Set Up Your Conda Earth Analytics Python Environment" } }, "source_map": [ 23 ] }, "nbformat": 4, "nbformat_minor": 5 }