Skip to content

Python Virtual Environments

ITk offline software relies primarily on python and C++. This page will describe how to isolate and virtualize your python installations, as well as setting up python virtual environments, to work with the various software toolings developed by the ITk community.

Administrative Access

The solution provided here will assume you do not have any adminstrative access to the machine(s) you are working on. There are, however, some fundamental core requirements on the OS (certain packages) for being able to compile different python versions as needed. This will be described in the next section. Beyond that, no sudo access is needed.

System Requirements

In order to set up pyenv correctly (to manage multiple python versions), your build environment needs to have certain packages. See the Suggested Build Environment wiki page for information for your system. Some information is reproduced here (but might be out-of-date later):

1
brew install openssl readline sqlite3 xz zlib tcl-tk

1
2
3
sudo apt update; sudo apt install make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

1
2
yum install gcc zlib-devel bzip2 bzip2-devel readline-devel sqlite \
sqlite-devel openssl-devel tk-devel libffi-devel xz-devel

1
2
dnf install make gcc zlib-devel bzip2 bzip2-devel readline-devel sqlite \
sqlite-devel openssl-devel tk-devel libffi-devel xz-devel

Particularly, these requirements look for at least make, gcc, zlib/xz, openssl, and readline. However, while readline is not really crucial for getting different python versions, it does improve your quality-of-life (QoL) by allowing for tab completion and using the arrow keys to navigate within the python interactive interpreter, so you will probably want it.

Installing

To install pyenv, just run the automatic installer

1
curl https://pyenv.run | bash

Once you do that, you will need to add some lines in your shells to add pyenv into your environment correctly. For bourne-shells, the following can be used depending on which files you have on your system:

1
2
3
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

1
2
3
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
echo 'eval "$(pyenv init -)"' >> ~/.profile

1
2
3
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile
echo 'eval "$(pyenv init -)"' >> ~/.bash_profile

For other shells (zsh, fish, etc), refer to the corresponding portion of the pyenv documentation.

Finally, you can finish your installation by running

1
exec $SHELL

to reload your shell/environment. At this point, pyenv -h should work correctly.

Usage

Installing python

Now that you have pyenv, you can use it to install python. This is done with one line:

1
pyenv install 3.10.4

and you're done.

Switching python

You have three options for switching your python version (in order of decreasing priority):

  1. shell: for current shell session,
  2. local: for current directory + subdirectories,
  3. global: for your account.

Simply run pyenv shell 3.10.4 to set it for the current shell session, or pyenv local 3.10.4 for current directory (which creates a .python-version file), or pyenv global 3.10.4 to make it the default python (which is overridden by the local/shell options).

Creating Virtual Environments

Python virtual environments are the best (and recommended) way of working with the ITk software as different software might have different requirements. There are two ways of doing this:

  1. python -m venv <name> to create the virtual environment locally in the current directory, using source <name>/bin/activate to activate the environment.
  2. pyenv virtualenv <version> <name> to create the virtual environment globally for your account (letting pyenv manage it), using pyenv activate <name> to activate the environment.

The second option is equivalent to the first, except the directory for the environment is just co-located with the other pyenv python installations, keeping your working directories cleaner. The former option has the only minor drawback that you might not know at first glance which python version that virtual environment was created with.

For the second option, to make this work, all you need to do is clone the virtualenv plugin into pyenv:

1
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv

and then you should be able to run

1
2
pyenv virtualenv 3.10.4 my-itk-env
pyenv activate my-itk-env

and it should work. For more information on the usage, see the pyenv docs.