1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
:orphan:
.. include:: links.inc
.. _virtual_envs:
===========================
Python virtual environments
===========================
If you plan to do regular work on astropy you should do your development in
a python virtual environment. Conceptually a virtual environment is a
duplicate of the python environment you normally work in with as many (or as
few) of the packages from your normal environment included in that virtual
environment. It is sandboxed from your normal python environment in the sense
that packages installed in the virtual environment do not affect your normal
environment in any way.
.. note::
"Normal python environment" means whatever python you are using when you
log in.
There are two options for using virtual environments; the choice of method is
dictated by the python distribution you use:
* If you use the anaconda python distribution you must use `conda`_ to make
and manage your virtual environments.
* If you use any other distribution you use `virtualenvwrapper`_; you *can not*
use `conda`_. As the name suggests, `virtualenvwrapper`_ is a wrapper around
`virtualenv`_.
In both cases you will go through the same basic steps; the commands to
accomplish each step are given for both `conda`_ and `virtualenvwrapper`_:
* :ref:`setup_for_env`
* :ref:`list_env`
* :ref:`create_env`
* :ref:`activate_env`
* :ref:`deactivate_env`
* :ref:`delete_env`
.. note::
+ You **cannot** use `virtualenvwrapper`_ or `virtualenv`_ within anaconda.
+ `virtualenvwrapper`_ works with bash and bash-like shells; see
:ref:`using-virtualenv` for alternatives.
.. _setup_for_env:
Set up for virtual environments
-------------------------------
* `virtualenvwrapper`_:
+ First, install `virtualenvwrapper`_, which will also install `virtualenv`_,
with ``pip install virtualenvwrapper``.
+ From the `documentation for virtualenvwrapper`_, you also need to::
export WORKON_HOME=$HOME/.virtualenvs
export PROJECT_HOME=$HOME/
source /usr/local/bin/virtualenvwrapper.sh
* `conda`_: No setup is necessary beyond installing the anaconda python
distribution.
.. _list_env:
List virtual environments
-------------------------
You do not need to list the virtual environments you have created before using
them...but sooner or later you will forget what environments you have defined
and this is the easy way to find out.
* `virtualenvwrapper`_: ``workon``
+ If this displays nothing you have no virtual environments
+ If this displays ``workon: command not found`` then you haven't done
the :ref:`setup_for_env`; do that.
+ For more detailed information about installed environments use
``lsvirtualenv``.
* `conda`_: ``conda info -e``
+ you will always have at least one environment, called ``root``
+ your active environment is indicated by a ``*``
.. _create_env:
Create a new virtual environment
--------------------------------
This needs to be done once for each virtual environment you want. There is one
important choice you need to make when you create a virtual environment:
which, if any, of the packages installed in your normal python environment do
you want in your virtual environment?
Including them in your virtual environment doesn't take much extra space--they
are linked into the virtual environment instead of being copied. Within the
virtual environment you can install new versions of packages like Numpy or
Astropy that override the versions installed in your normal python environment.
The easiest way to get started is to include in your virtual environment the
packages installed in your your normal python environment; the instructions
below do that.
In everything that follows, ``ENV`` represents the name you give your virtual
environment.
**The name you choose cannot have spaces in it.**
* `virtualenvwrapper`_:
+ Make an environment called ``ENV`` with all of the packages in your normal
python environment::
mkvirtualenv --system-site-packages ENV
+ Omit the option ``--system-site-packages`` to create an environment
without the python packages installed in your normal python environment.
+ Environments created with `virtualenvwrapper`_ always include `pip`_
and `setuptools <https://pythonhosted.org/setuptools/>`_ so that you
can install packages within the virtual environment.
+ More details and examples are in the
`virtualenvwrapper command documentation`_.
* `conda`_:
+ Make an environment called ``ENV`` with all of the packages in your main
anaconda environment::
conda create -n ENV anaconda
+ More details, and examples that start with none of the packages from
your normal python environment, are in the
`documentation for the conda command`_ and the
`blog post announcing anaconda environments`_.
.. _activate_env:
Activate a virtual environment
------------------------------
To use a new virtual environment you may need to activate it;
`virtualenvwrapper`_ will try to automatically activate your new environment
when you create it. Activation does two things (either of which you could do
manually, though it would be inconvenient):
* Put the ``bin`` directory for the virtual environment at the front of your
``$PATH``.
* Add the name of the virtual environment to your command prompt. If you have
successfully switched to a new environment called ``ENV`` your prompt should
look something like this: ``(ENV)[~] $``
The commands below allow you to switch between virtual environments in
addition to activating new ones.
* `virtualenvwrapper`_: Activate the environment ``ENV`` with::
workon ENV
* ` conda`: Activate the environment ``ENV`` with::
source activate ENV
.. _deactivate_env:
Deactivate a virtual environment
--------------------------------
At some point you may want to go back to your normal python environment. Do
that with:
* `virtualenvwrapper`_: ``deactivate``
+ Note that in ``virtualenvwrapper 4.1.1`` the output of
``mkvirtualenv`` says you should use ``source deactivate``; that does
not seem to actually work.
* `conda`_: ``source deactivate``
.. _delete_env:
Delete a virtual environment
----------------------------
In both `virtualenvwrapper`_ and `conda`_ you can simply delete the directory in
which the ``ENV`` is located; both also provide commands to make that a bit easier.
* `virtualenvwrapper`_: ``rmvirtualenv ENV``
* `conda`_: ``conda remove --all -n ENV``
.. _documentation for virtualenvwrapper: http://virtualenvwrapper.readthedocs.io/en/latest/install.html
.. _virtualenvwrapper command documentation: http://virtualenvwrapper.readthedocs.io/en/latest/command_ref.html
.. _documentation for the conda command: http://docs.continuum.io/conda/examples/create.html
.. _blog post announcing anaconda environments: http://www.continuum.io/blog/conda
|
