Isadora updates Python to maintain compatibility with NumPy. For stability, Pythoner uses the latest Python release listed by Python.org as receiving security updates, rather than automatically moving to every newer release listed as receiving bug fixes.

Updating Virtual Environments After a Python Update

Over time, Isadora updates Pythoner to use newer versions of Python. When this happens, virtual environments created with the previous Python version must be recreated for the updated version of Pythoner.

The chart above outlines each Pythoner release in which a new Python version was included. 

For example, earlier Pythoner releases used Python 3.10, while Pythoner 1.0.8 uses Python 3.12.10. A virtual environment created for Python 3.10 will not work correctly with Pythoner when it is running Python 3.12.

Pythoner’s included virtual-environment tools

Pythoner includes several support scripts that handle the most common virtual-environment tasks. For the standard workflow described in this article, you should use these scripts rather than manually editing environment files or entering commands in Terminal or Command Prompt.

The scripts are installed in the Python_Support_Scripts folder and can be used to:

• Create a new virtual environment.
• Install Python packages into an existing virtual environment.
• Select a shared virtual environment for Pythoner; the script updates ActiveVirtualEnvironmentPath.txt for you.
• Create a project-specific virtual_env folder from a requirements.txt file.

In this article, “activating” a virtual environment means selecting it for Pythoner to use.

Why must the virtual environment be recreated?

Pythoner contains and runs a specific version of Python.

A virtual environment does not replace Pythoner’s internal Python with a different version. Instead, the virtual environment is created to work with the specific Python version included with Pythoner and provides an isolated location for additional Python packages.

Because of this, a virtual environment created using Python 3.10 cannot simply be connected to Pythoner when Pythoner has been updated to Python 3.12.

Changing ActiveVirtualEnvironmentPath.txt only tells Pythoner which virtual environment to use. It does not convert an older environment or make it compatible with a newer Python version.

When Pythoner’s Python version changes, the correct process is:

1. Record the packages installed in the old environment.
2. Keep the old environment as a backup.
3. Create a new environment using the updated Pythoner.
4. Reinstall the required packages into the new environment.

Does this affect your project?

Pythoner is using its internal Python

You do not need to rebuild a virtual environment when you have not created or selected one.

In this configuration, Pythoner uses the Python interpreter contained inside the Pythoner plugin. When Pythoner is updated, its internal Python version is updated with it.

You should still open and test your project after updating Isadora, but there is no separate virtual environment to recreate.

Pythoner is using a virtual environment

You must create a new virtual environment when Pythoner is using either:

• A shared virtual environment selected through ActiveVirtualEnvironmentPath.txt.
• A project-specific environment stored in a folder named virtual_env beside the Isadora .izz file.

The old environment should be kept until the project has been successfully rebuilt and tested.

The three Pythoner environment configurations

Pythoner can run using one of three configurations.

1. Pythoner’s internal Python

In the simplest configuration, no virtual environment has been selected.

Pythoner uses the Python version included inside the Pythoner plugin. There is no separate environment folder for you to manage.

After updating Isadora

Open and test the project.

You do not need to recreate a virtual environment because the project was not using one.

2. A shared virtual environment

A shared virtual environment is stored somewhere on your computer, separately from the Isadora project.

Pythoner uses the file named:

ActiveVirtualEnvironmentPath.txt

to locate this environment.

A shared environment may be used by one project or by several projects that require the same Python packages.

Recommended environment names

Include the Python version in the folder name:

venv_mediapipe_py310
venv_mediapipe_py312

This makes it clear which version of Python each environment was created for and prevents the new environment from overwriting the old one.

After updating Isadora

1. Keep the old environment.
2. Create a new environment using the support scripts supplied with the current Pythoner.
3. Give the new environment a different, versioned name.
4. Install the project’s required packages into the new environment.
5. Run the included activate-virtual-environment script and select the new environment.
   The script updates ActiveVirtualEnvironmentPath.txt for you. 
6. Quit and restart Isadora.
7. Open and test the project.

Once Pythoner has selected an environment, that environment remains active until Isadora is quit and restarted.

3. A project-specific virtual_env folder

Pythoner can automatically use a virtual environment stored beside an Isadora project.

The environment folder must be named exactly:

virtual_env

For example:

My Isadora Project/
├── My Project.izz 
├── requirements.txt 
├── virtual_env/
└── python_modules/

When Isadora is started fresh and a project containing a valid virtual_env folder is opened, Pythoner will use that project-specific environment instead of the environment listed in ActiveVirtualEnvironmentPath.txt.

Pythoner can use only one environment during an Isadora session. If Pythoner has already initialized another environment, opening a different project will not switch to its project-specific virtual_env folder. Quit and restart Isadora before opening the project whose environment you want to use.

After updating Isadora

Do not immediately delete or overwrite the existing virtual_env folder.

Instead:

1. Quit Isadora.
2. Rename the old environment to record its Python version:

virtual_env_py310_backup

3. If you have a requirements.txt file, run the included virtual-environment-from-requirements script. The script creates a new folder named virtual_env beside the .izz file and installs the packages listed in requirements.txt.
4. If you do not have a requirements.txt file, use the included scripts to create a new environment named virtual_env beside the .izz file and install the packages required by the project.
5. Restart Isadora.
6. Open and test the project.

Only a folder named exactly virtual_env can be selected automatically, and it must be present beside the .izz file when Pythoner initializes in a fresh Isadora session. 

Keeping compatibility with an older Isadora version

When the project must continue working with an older Isadora version, the safest approach is to duplicate the complete project folder before updating:

My Project - Previous Isadora/
├── My Project.izz
└── virtual_env/

My Project - Current Isadora/
├── My Project.izz
└── virtual_env/

Each project copy can then contain the correct environment for its version of Pythoner.

Keeping separate project copies also protects the older .izz file. Files saved in a newer Isadora file format may not open in an older Isadora version.

Before updating Isadora

Preparing before the update is the easiest and most reliable approach.

Step 1: Open the project in the working Isadora version

Quit Isadora, reopen the working Isadora version, and open only the project you want to update. Confirm that its Pythoner code and installed packages are working correctly. 

Step 2: Identify which configuration the project uses

Determine whether the project uses:

1. Pythoner’s internal Python;
2. a shared environment selected using ActiveVirtualEnvironmentPath.txt; or
3. a project-specific virtual_env folder.

In current Isadora versions, the following menu command can help identify the active environment:

Help → Open Plugin Folder → Python Virtual Environment

Isadora will report information about whether Pythoner is active and which environment it is using.

Step 3: Create or update requirements.txt

A requirements.txt file records the Python packages needed by the project. It can then be used to install those packages into a newly created environment.

Keep requirements.txt beside the Isadora project file:

My Isadora Project/
├── My Project.izz 
├── requirements.txt 
└── virtual_env/

Using DX Python Tools

The DX Python Tools are a set of User Actors which provide a range of useful utilities, and system information.
The DX – PY – Virtual Environment Manager can create a requirements.txt file from the currently active environment, including the Python version.

It can also create a new environment from an existing requirements.txt file and provides actions for managing ActiveVirtualEnvironmentPath.txt.

Advanced: Command-line method 

Advanced users can create a requirements file from the active environment using:

python -m pip freeze > requirements.txt

Make sure the command is being run using the Python executable belonging to the environment you want to record.

Step 4: Preserve the working environment

Do not overwrite the original environment.

For a shared environment, create the new version beside the original:

venv_project_py310 
venv_project_py312

For a project-specific environment, duplicate the project folder or rename the existing virtual_env folder before creating its replacement.

Step 5: Update Isadora

Install the new version of Isadora and Pythoner.

Step 6: Create a new virtual environment

Use the virtual-environment creation scripts supplied with the current Pythoner version.

The new environment must be created using the updated Pythoner so that it matches Pythoner’s current Python version.

Step 7: Install the requirements

Use the saved requirements.txt file to install the project’s required packages into the new environment.

Advanced users can use:

python -m pip install -r requirements.txt

Step 8: Connect the new environment

For a shared environment, run the included activate-virtual-environment script and select the new environment. The script updates ActiveVirtualEnvironmentPath.txt for you. 

For a project-specific environment, make sure the new folder is named exactly virtual_env and is located beside the .izz file.

Step 9: Restart Isadora

Quit Isadora completely and reopen it before testing the project.

I already updated and my project no longer works

Do not delete the old virtual environment.

It may still contain the information needed to recreate your project environment.

If you already have a requirements.txt file

When a current requirements file is available:

1. Keep the old environment as a backup.
2. Create a new environment using the current Pythoner.
3. Install the packages listed in requirements.txt.
4. Connect the new environment using the appropriate method.
5. Quit and restart Isadora.
6. Test the project.

This is the quickest recovery path.

You can still run the old project with the previous Pythoner

Temporarily open the project using the earlier version of Isadora and Pythoner that matches the old environment.

Then:

1. Select or load the old environment.
2. Confirm that the project still works.
3. Create a requirements.txt file from the working environment using DX Python Tools or the advanced command-line method described above. 
4. Return to the current Isadora and Pythoner version.
5. Create a new environment.
6. Install the packages from requirements.txt.   
7. Restart Isadora and test the project.

Do not save your only copy of the project using the newer Isadora version if you still need to open it in the older version.

You no longer have the previous Pythoner version

The old virtual environment may still be present, but it may depend on the older Python version included with the previous Pythoner.

To recover the environment:

1. Keep the old environment unchanged.
2. Install the matching older Isadora version, making sure that Pythoner is included during installation. This temporarily restores the matching Pythoner and Python version.
3. Open the older project and create a requirements.txt file from the old environment using DX Python Tools or the advanced command-line method described above.
4. Reinstall the current Isadora version, making sure that the current Pythoner is included.
5. Create the replacement environment and install the saved requirements.
6. Restart Isadora and test the project.

By default, installed Isadora versions use the Pythoner plugin in the same shared Isadora Plugins folder. Installing another Pythoner version replaces the version in that location. An older Isadora version may therefore load an incompatible Pythoner version or may be unable to load Pythoner correctly.

Advanced users who maintain separate application and plugin locations may use a different workflow.

It is recommended that you update and test all projects that use Pythoner whenever you update Isadora.

Avoid attempting to convert the old environment by manually editing its internal files. This does not reliably update the environment to the new Python version and may leave it unusable.

The old environment’s Python command still works

Some advanced users may be able to run the Python executable located inside the old environment directly, even if Pythoner can no longer select it.

macOS

"/path/to/old_environment/bin/python" -m pip freeze > requirements.txt

Windows

"C:\path\to\old_environment\Scripts\python.exe" -m pip freeze > requirements.txt

This creates requirements.txt without requiring the environment to be activated inside Pythoner.

This method will not work if the old environment depends on a Python installation that is no longer available. This is especially possible after the embedded Python version has been replaced.

The old environment cannot be run

As a last resort, reconstruct the requirements from:

• The package imports used in your Python scripts.
• Notes or documentation created for the project.
• A collaborator’s working copy.
• A project backup.
• An older requirements.txt file.
• Package names remembered from the original setup.

Create a new environment and install the required packages. Test the project after each major package is added.

An advanced user may also be able to inspect the package information remaining inside the old environment, but this should be treated as a recovery technique rather than the normal update process.

What if a package will not reinstall?

A package version that worked with the previous Python version may not support the newer Python version.

For example, a package version installed under Python 3.10 may not provide a compatible release for Python 3.12.

When installation fails:

1. Identify which package produced the error.
2. Check whether a newer version of that package supports the current Python version.
3. Update its entry in requirements.txt.
4. Run the installation again.
5. Test the project carefully.

A newer package release may contain changes that affect your Python code.

Once the rebuilt environment is working, create a new requirements.txt file from it. This updated file will record the package versions used by the new environment.

Record the environment version

Add a simple text file named version.txt inside each new environment.

For example:

Python Version: 3.12.10
Pythoner Version: 1.0.8
Isadora Version: 4.5.1
Created: August 4, 2026
Purpose: MediaPipe environment for My Project

For a shared environment:

venv_mediapipe_py312/ 
├── version.txt 
└── ...

For a project-specific environment:

My Isadora Project/
├── My Project.izz 
├── requirements.txt 
└── virtual_env/
    ├── version.txt   
    └── ...

This file is not required by Pythoner. Adding it is a recommended practice because it makes the environment easier to identify later. 

Recommended project workflow

For future projects:

1. Keep each Isadora project in its own folder.
2. Keep requirements.txt beside the .izz file.
3. Update requirements.txt whenever packages are added, removed, or updated.
4. Include the Python version in the names of shared environments.
5. Add version.txt to each environment.
6. Keep the old environment until the updated project has been fully tested.
7. Keep a backup of the original .izz project before opening it in a newer Isadora version.

Example project structure:

My Isadora Project/
├── My Project.izz 
├── requirements.txt 
├── python_modules/ 
└── virtual_env/
    └── version.txt

The virtual environment should be considered replaceable. The requirements.txt file is the important record that allows the environment to be recreated.

DX Python Tools for Isadora

DX Python Tools is an optional collection of Isadora User Actors that can simplify Pythoner environment management.

The tools can:

• Create an environment from requirements.txt.
• Create requirements.txt from the active environment.
• Update ActiveVirtualEnvironmentPath.txt.
• Validate packages listed in a requirements file.
• Display Python environment and path information.
• Create a project-specific virtual_env environment. 

These tools cannot convert an environment from one Python version to another. They are most useful for recording a working environment and rebuilding it after an update.

Using them regularly to keep requirements.txt current can make future Pythoner updates much easier.

Quick reference

I use Pythoner’s internal Python

    Open and test the project after updating. There is no separate virtual environment to rebuild.

I use a shared environment

    Keep the old environment, create a new versioned environment, install the requirements, and run activate-virtual-environment to select it. 

I use a project-specific virtual_env folder 

    Back up or rename the old folder, and then run virtual-environment-from-requirements to create a new virtual_env folder from requirements.txt. 

I updating before creating requirements.txt

    Keep the old environment. Run it using the matching earlier Pythoner version, create requirements.txt, and then rebuild the environment with the current Pythoner.

I cannot run the old environment

    Restore the matching Pythoner version, contact TroikaTronix Technical Support, or manually reconstruct the required package list.