Creating and Using Python Virtual Environments¶

Both for the development of Python codes as well as running programs, the creation of a Python virtual environment is recommended. Not only does it prevent version conflicts and ever-growing installations, it also allows separating production and test scenarios.

Virtual Environments at CERN with Acc-Py¶

The BE/CO Acc-Py distribution at CERN (at /acc/local/share/python/acc-py/base/pro) allows one to create Python virtual environments immediately configured for internal CERN index and apps. Acc-Py is the official way to manage one's Python environments at CERN for the foreseeable future. You can think of it like a miniconda installation with all the CERN-specific hooks in place, with additional command line utilities for CERN apps.

However, because of how Python virtual environments work under the hood, the python executable in any such virtual environment is a symlink to the Acc-Py distribution's base Python executable. This means any machine wanting to use this executable needs to also have read access to the location of the Acc-Py distribution in /acc/, which means having access to the Technical Network - not always the case. For this reason, one might want to install a standalone Acc-Py distribution somewhere else, for instance on afs.

The following section goes over installing a standalone Acc-Py distribution, which is how we manage the OMC environments. If you already have one at the ready or plan to use the BE/CO-provided Acc-Py, then skip ahead.

Installing a Standalone Acc-Py¶

The Acc-Py wiki has a section linking to installers one can download. From there download the desired file, curl or wget will work great if you are ssh-ed into a server.

A default distribution is recommended but installation is identical for other distributions (pro, devel, rc). As of the last update of this walk-through, this corresponds to the acc-py-2026.01-installer.sh file, for a distribution based on Python 3.14.

The installer itself is an executable to be called from the command line. You might need to chmod u+x the file once downloaded.

The installer needs to be run on the command line, providing the installation root: This does not have to be an existing directory, it can be created at install.

Once the installation root determined (here dist_location), call the installer:

bash acc-py-2026.01-installer.sh --installation-root /path/to/dist_location

Wait for the installation script to finish - if you have installed anaconda or miniconda in the past, the process and its output will feel familiar. The created structure should look like (obtained with tree -L 3 dist_location):

dist_location/
├── apps
│   └── acc-py-cli
│       └── latest
└── base
    └── 2026.01
        ├── bin
        ├── _conda
        ├── etc
        ├── include
        ├── lib
        ├── man
        ├── pip.conf
        ├── setup.sh
        ├── share
        └── ssl -> /etc/pki/tls

Creating Virtual Environments with Acc-Py¶

To make the command line tools available in the current shell, source the setup.sh script in the installed Acc-Py distribution:

source dist_location/base/2026.01/setup.sh

You should see a confirmation message output that reads:

=>  Acc-Py base 2026.01 is now active within this shell.

You now have access to the acc-py command line tool, which you can verify by running acc-py -h and checking that you get the help command output. The command to create a virtual environment is based on the built-in venv module and should feel familiar if you know venv. To create a virtual environment, run:

acc-py venv /path/to/environment/

This will create a virtual environment at /path/to/environment/. To activate this environment, run:

source /path/to/environment/bin/activate

You can confirm you are running the appropriate Python with which python, which should point to /path/to/environment/bin/python. You can then install packages in this environment with:

python -m pip install <package-name>

Using python -m pip instead of simply pip guarantees that the right executable is called. Thanks to Acc-Py, everything is already set up to look into the CERN index, which is where many CERN apps and packages have to be installed from. Different ways to use pip for package installations are nicely explained in the official documentation.

Using Your Virtual Environment¶

When your virtual environment has all the packages you wish, anyone with access to the distribution's python executable (because all virtual environments will symlink to that) can use it. To use the environment's Python, one can either:

• First source /path/to/environment/bin/activate then call python.
• Call the full path to the python executable /path/to/environment/bin/python directly.