Python virtual environments with MATLAB

How can I use virtual environments with MATLAB's Python Interface?

Answer 1

[MathWorks Support Team]

This document contains instructions for using a Python virtual environment, which can be used with these products: MATLAB Python Interface, the MATLAB Engine API for Python, MATLAB Compiler SDK for Python, or the MATLAB Production Server Python Client.

Starting in R2026a, it is recommended that you use the Python view in the External Languages panel to manage virtual environments that you will use with MATLAB Python Interface or the MATLAB Engine API for Python. In the panel, you can switch Python environments, add or create environments, manage and share libraries, change the execution mode, and remove or delete environments. For more details see: Manage Python Environments Using External Languages Panel.

If you are not using the Python panel, this example demonstrates how to use a virtual environment with MATLAB's Python Interface. Except where indicated, the content applies to the other products listed above. These instructions are OS-dependent. 

• Windows
  • Setup steps in Windows Command Prompt
  • Setup steps in MATLAB
• Linux/macOS
  • Setup steps in Linux/macOS terminal
  • Setup steps in MATLAB

Windows

Setup steps in Windows Command Prompt

In this example, python.exe is located in the following directory:

C:\Users\username\AppData\Local\Programs\Python

Pass the --version flag to the Python interpreter to determine its version, if necessary.  

C:\Users\username>  C:\Users\username\AppData\Local\Programs\Python\python --version 

1) Create a virtual environment

Create a virtual environment named "py38" under C:\users\username. 

C:\Users\username>  C:\Users\username\AppData\Local\Programs\Python\python -m venv C:\Users\username\py38 

2)  Activate the virtual environment

C:\Users\username> C:\Users\username\py38\Scripts\activate.bat 

Once activated, you should see the Python virtual environment name (py38) at the start of the command prompt.

(py38) C:\Users\username>

3) Install packages 

Install any Python packages that are required for your project. For example, to install version 3.1 of h5py, execute the following command. 

(py38) C:\Users\username> python -m pip install h5py==3.1 

Any packages installed while a virtual environment is activated will only be accessible from that virtual environment. 

4) Verify that modules can be loaded in Python

Start Python

(py38) C:\Users\username> python
>>> import h5py 

5) Find the location of the Python executable in the virtual environment 

(py38) C:\Users\username$ python 
>>> import sys 
>>> sys.executable 

In this case, a symbolic link to the Python executable is located at the following path:

C:\Users\username\py38\Scripts\python.exe

Setup steps in MATLAB

Start MATLAB from the Command Prompt window or using the Start menu.

1) Set the Python environment (applies to Python Interface only)

Set the Python environment to match the location of the Python executable in the virtual environment. 

Using the same Python 3.8 example as above, and changing the execution mode to OutOfProcess to avoid library conflicts: 

>>  pyenv('Version', ... 
            'C:\Users\username\py38\Scripts\python', ... 
            'ExecutionMode','OutOfProcess') 
ans = 
  PythonEnvironment with properties: 
          Version: "3.8" 
       Executable: "C:\Users\username\py38\Scripts\python.EXE" 
          Library: "C:\Users\gmkep\AppData\Local\Programs\Python\Python38\python38.dll" 
             Home: "C:\Users\username\py38" 
           Status: NotLoaded 
    ExecutionMode: OutOfProcess 

2) Use the library (applies to Python Interface only)

In this example, we will load the library.

>> py.importlib.import_module('h5py') 
ans = 
  Python module with properties: 
                     bartlett: [1×1 py.function] 
                      float32: [1×1 py.type] 
                  right_shift: [1×1 py.numpy.ufunc] 
                        isnan: [1×1 py.numpy.ufunc] 
...

 

Linux/macOS

Setup steps in Linux/macOS terminal

In this example, python3 is located in the following location:  

/usr/bin/python3 

Pass the --version flag to the Python interpreter to determine its version. 

/home/username$ /usr/bin/python3 --version 
Python 3.8.2 

1) Create a virtual environment

Create a virtual environment named py38 under /home/username. 

/home/username$  /usr/bin/python3 -m venv /home/username/py38 

2) Activate the virtual environment

The following example assumes that the bash shell is being used. For the csh or tcsh shell, replace "activate" by "activate.csh"

/home/username$ source /home/username/py38/bin/activate

Once activated, you should see the Python virtual environment name (py38) at the start of the command prompt.

(py38) /home/username$

3) Install packages

Install any Python packages that are required for your project. For example, to install version 3.1 of h5py, execute the following command. 

(py38) /home/username$ python -m pip install h5py==3.1 

4) Verify that module can be loaded in Python

Start Python and import the module.

(py38) /home/username$ python
>>> import h5py

5) Find the location of the Python executable in the virtual environment

One way to find the location of the executable is to start Python in the virtual environment terminal, and execute the following commands.

(py38) /home/username$ python
>>> import sys
>>> sys.executable

In this case, a symbolic link to the Python executable is located at the following path. 

/home/username/py38/bin/python 

Setup steps in MATLAB

1) Start MATLAB from the terminal

(py38) /home/username$ matlab

2)  Set the Python environment (applies to Python Interface only)

Set the Python environment "Version" field to point to a symbolic link to the Python executable in the virtual environment. Using the same Python 3.8 example as above and changing the execution mode to OutOfProcess to avoid library conflicts: 

>>  pyenv('Version', ... 
            '/home/username/py38/bin/python', ... 
            'ExecutionMode','OutOfProcess') 
ans = 
  PythonEnvironment with properties: 
          Version: "3.8" 
       Executable: "/home/username/py38/bin/python" 
          Library: "<library path>/libpython3.8.so" 
             Home: "/home/username/py38" 
           Status: NotLoaded 
    ExecutionMode: OutOfProcess 

3) Use the module (applies to Python Interface only)

In this example we will load the h5py module.

>> py.importlib.import_module('h5py') 
ans = 
  Python module with properties: 
                     get_enum: [1×1 py.builtin_function_or_method] 
                     check_enum_dtype: [1×1 py.builtin_function_or_method] 
                     Reference: [1×1 py.type]