Installing PlasmaPy for Development
Table of Contents
Obtaining PlasmaPy source code
After creating your GitHub account, go to PlasmaPy’s GitHub repository and fork a copy of PlasmaPy to your account.
To access Git commands on Windows, try Git Bash.
Next you must clone your fork to your computer. Go to the directory that will host your PlasmaPy directory, and run one of the following commands (after changing your-username to your username). If you would like to use HTTPS (which is the default and easier to set up), then run:
git clone https://github.com/your-username/PlasmaPy.git
SSH is a more secure option, but requires you to set up an SSH key beforehand. The equivalent SSH command is:
git clone email@example.com:your-username/PlasmaPy.git
After cloning, we must tell git where the development version of PlasmaPy is by running:
cd PlasmaPy git remote add upstream git://github.com/PlasmaPy/PlasmaPy.git
To check on which remotes exist, run
git remote -v. You should get
something like this:
origin firstname.lastname@example.org:namurphy/PlasmaPy.git (fetch) origin email@example.com:namurphy/PlasmaPy.git (push) upstream firstname.lastname@example.org:PlasmaPy/PlasmaPy.git (fetch) upstream email@example.com:PlasmaPy/PlasmaPy.git (push)
Setting up an environment for development
Setup procedures for the two most popular virtual environments, conda and virtualenv, are listed below.
To set up a development environment for PlasmaPy, we strongly recommend the Anaconda distribution.
After installing Anaconda, launch any conda environment. By default,
conda installs a
root environment, which you should be able to
source /home/user/anaconda3/bin/activate root
/home/user/anaconda3/ can be swapped to wherever your anaconda
On newer versions of Anaconda the recommended activation process has changed to:
. /home/user/anaconda3/etc/profile.d/conda.sh conda activate
On Windows, the way to do this is via running
from the Start Menu.
Git Bash may also work if you have added
Create your environment
Having activated Anaconda, enter PlasmaPy’s repository root directory and create an environment with our suggested packages by executing the following:
conda create -n plasmapy python=3.10
You may now enter the environment via
source activate plasmapy
On Windows, skip the
source part of the previous command.
In newer Conda versions, the command to run is
conda activate plasmapy
Create a directory for holding the PlasmaPy repository, move into it and create the virtual environment
virtualenv -p python3 venv
You may need to make sure that this directory’s path doesn’t contain any spaces, otherwise virtualenv may throw an error.
Your virtual environment should now be created. If you run
ls venv you
will notice that virtualenv has created a number of subdirectories:
include/. This is why we’re not creating the
virtualenv within the repository itself - so as to not pollute it. To
activate the virtualenv you will run:
You should now see that your shell session is prepended with (plasmapy), like so:
This indicates that the virtualenv is running. Congratulations! When your’re done working on PlasmaPy, you can deactivate the virtualenv by running
Now that you have plasmapy on your local computer and you have a virtual environment, you will want to “install” this development version of PlasmaPy along with its dependencies. Start by activating your virtual environment.
Then, set up the development version of PlasmaPy which you just cloned by moving into the root directory of the cloned repo and running the following there:
(plasmapy) user@name:~/programming/plasmapy$ pip install --editable ".[tests,docs]"
You should now be all set to run development versions of PlasmaPy
import plasmapy in your test scripts!
--editable flag will create a soft link to your cloned
repository. Any changes in Python code you make there will be there
import plasmapy from an interactive session.
If you are not working within a virtual environment, this may end in
a permission error — this can be avoided via also adding the
--user flag. But seriously, use a virtual environment and spare
yourself the trouble.
Running anaconda with virtualenv
If you are running the Anaconda suite and want to use virtualenv to
setup your virtual environment, you will have to let the system know
where the Python interpreter can be found. On Linux this is done with
(for example, assuming having installed Anaconda into
Exporting the library path to the dynamic linker will only last for the duration of the current shell session.
You will have to add the python library directory to LD_LIBRARY_PATH, as described in a previous step, prior to activating the virtualenv for every new shell session.
PlasmaPy uses the
pre-commit framework to perform validations and
automatically apply a consistent style to code contributions. Using
pre-commit helps us find errors and shortens code reviews. PlasmaPy’s
pre-commit suite includes hooks such as:
check-astto verify that the Python code is valid.
trailing-whitespaceto remove trailing whitespace.
black to format code.
isort to sort imports.
nbqa to format notebooks.
Most of the changes required by
pre-commit can be applied
automatically. To apply these changes in a pull request, add a comment
pre-commit.ci autofix. After doing this, be sure to pull
the changes from GitHub to your computer with
pre-commit locally, open a terminal, enter the directory of
the PlasmaPy repository, and run:
pip install pre-commit pre-commit install
Now suppose we added some trailing whitespace to
and attempted to commit it. If
pre-commit has been installed, then
trailing-whitespace hook will cause
pre-commit to fail while
some_file.py to remove the trailing whitespace.
$ git add some_file.py $ git commit -m "Add trailing whitespace" Trim Trailing Whitespace.................................................Failed - hook id: trailing-whitespace - exit code: 1 - files were modified by this hook
At this point it will be necessary to run these two commands again to
commit the changes. The changes made by
pre-commit will be unstaged and
thus could be seen by running
git diff. Sometimes
not be able to automatically fix the files, such as when there are
syntax errors in Python code. In these cases, the files will need to be
changed manually before running the
git add and
commands again. Alternatively, the
pre-commit hooks can be skipped
git commit --no-verify instead.
pre-commit configuration is given in
After adding or updating
pre-commit hooks, run the following command to
apply the changes to all files.
pre-commit run --all-files