The PyUtils class provides a set of static methods that work with the embedded Python that ships with IDL.

See IDL to Python for details on using Python within IDL.

Tip: If you are using your own flavor of Python (instead of the embedded Python within IDL), you will need to call PyUtils.Load to pick the appropriate Python bridge library first. For example:

IDL> PyUtils.Load, 'python313'  ; your Python is 3.13

Methods

PyUtils::Load

The PyUtils::Load static method is used to manually load the IDL-Python bridge and target a specific Python version.

Note: If you want to use the embedded Python that ships with IDL and ENVI, you do not need to call PyUtils.Load. The embedded Python will be automatically loaded when the first Python command is used in your IDL session. The Load method is only necessary if you want to connect IDL to a different version of Python on your system.

Note: To connect to a particular version of Python, you need to install that Python version on your system and properly configure it to work with IDL. This includes installing numpy. For detailed instructions see Installation - IDL to Python Bridge.

Example

Connect IDL to your locally-installed Python version:

IDL> PyUtils.Load, 'python313'
% Loaded DLM: PYTHON313.
% PYTHON_INIT: C:\Users\myusername\AppData\Local\Programs\Python\Python313.

Syntax

PyUtils.Load, Version

Arguments

Version

Set this argument to a scalar string giving the name of the Python version. This string should have the format "pythonXY" where X and Y are the major and minor version numbers of the Python installation. For example, to load Python 3.13, set version to "python313".

This string must correspond to one of the IDL Python bridge libraries that ship with IDL. For a list of these libraries, run the following code:

IDL> help, /dlm, output = output
IDL> output[where(output.startsWith('** PYTHON'))]
** PYTHON311 - IDL Bridge to Python 3.11 (not loaded)
** PYTHON312 - IDL Bridge to Python 3.12 (not loaded)
** PYTHON313 - IDL Bridge to Python 3.13 (not loaded)

Keywords

None

PyUtils::PipInstall

The PyUtils::PipInstall static method installs a new Python package into the user's .idl package folder and makes it available to the embedded Python. This procedure only works with the embedded Python that ships with IDL. Calling this while a different Python is loaded will result in an error.

Example

Install the Beautiful Soup package, which is useful for parsing HTML and XML files:

IDL> PyUtils.PipInstall, 'beautifulsoup4'
Looking in indexes: https://pypi.python.org/simple
Collecting beautifulsoup4
Installing collected packages: beautifulsoup4
Successfully installed beautifulsoup4-4.13.3
Package beautifulsoup4 successfully installed in C:\Users\myusername\.idl\idl\python_idlx_x.

Test the package:

IDL> bs4 = Python.Import('bs4')
IDL> myhtml = '<html><title>IDL is great</title></html>'
IDL> soup = bs4.BeautifulSoup(myhtml, 'html.parser')
IDL> print, soup.title.string
IDL is great

Syntax

PyUtils.PipInstall, Package, OUTPUT=variable, /UPGRADE, VERSION=string

Arguments

Package

A string giving the name of the package to install. This package name should match one of the packages on the standard pip repository manager or your current package manager.

Tip: Non-standard Python package managers are typically stored in the .pypirc file within your home directory, along with any required usernames or passwords. The creation and format of this file is beyond the scope of IDL's PyUtils class.

Keywords

OUTPUT

By default, this method prints out the information to the IDL console. If the OUTPUT keyword is set to a named variable then the output will be returned in that variable instead.

Note: If an error occurs, IDL will halt execution and print the error message to the IDL console, regardless of the OUTPUT keyword.

UPGRADE

Set this keyword to upgrade the package if it is already installed. If the package is not already installed, then this keyword is ignored and the latest version is installed.

VERSION

Set this keyword to a string giving the version to install. By default, this method installs the latest version.

PyUtils::PipUninstall

The PyUtils::PipUninstall static method removes an existing Python package from the user's .idl package folder. This procedure only works with the embedded Python that ships with IDL. Calling this while a different Python is loaded will result in an error.

Example

Remove the Beautiful Soup package:

IDL> PyUtils.PipUninstall, 'beautifulsoup4'
Found existing installation: beautifulsoup4 4.13.3
Uninstalling beautifulsoup4-4.13.3:
Successfully uninstalled beautifulsoup4-4.13.3
Package beautifulsoup4 successfully removed from C:\Users\myusername\.idl\idl\python_idlx_x.

Syntax

PyUtils.PipUninstall, Package, /ALL, OUTPUT=variable

Arguments

Package

A string giving the name of the package to remove.

Keywords

ALL

If this keyword is set then all user packages will be removed.

OUTPUT

By default, this method prints out the information to the IDL console. If the OUTPUT keyword is set to a named variable then the output will be returned in that variable instead.

Note: If an error occurs, IDL will halt execution and print the error message to the IDL console, regardless of the OUTPUT keyword.

PyUtils::PipList

The PyUtils::PipList static method retrieves the list of installed Python packages, from either the user's .idl folder or built into the embedded Python. This procedure only works with the embedded Python that ships with IDL. Calling this while a different Python is loaded will result in an error.

Example

IDL> PyUtils.PipList, /user
 
Package           Version
----------------- -------
beautifulsoup4    4.13.3
soupsieve         2.6
typing_extensions 4.13.0
 
IDL> PyUtils.PipList, /system
 
Package            Version
------------------ -----------
numpy              2.2.3
envipyengine       1.0.9
regex              2024.11.6
...

Syntax

PyUtils.PipList, OUTPUT=variable, /SYSTEM, /USER

Arguments

None

Keywords

OUTPUT

By default, this method prints out the information to the IDL console. If the OUTPUT keyword is set to a named variable then the output will be returned in that variable instead.

Note: If an error occurs, IDL will halt execution and print the error message to the IDL console, regardless of the OUTPUT keyword.

SYSTEM

Set this keyword to only return a list of the system packages. The default behavior is to return a list of all installed packages.

USER

Set this keyword to only return a list of the user packages. The default behavior is to return a list of all installed packages.

PyUtils::PipShow

The PyUtils::PipShow static method retrieves and displays information about an installed package. This procedure only works with the embedded Python that ships with IDL. Calling this while a different Python is loaded will result in an error.

Example

IDL> PyUtils.PipShow, 'pandas'
 
Name: pandas
Version: 2.x.x
Summary: Powerful data structures for data analysis, time series, and statistics
Home-page: https://pandas.pydata.org
...
Location: C:\Program Files\NV5\IDLxx\bin\bin.x86_64\idl-python3xx\Lib\site-packages
Requires: numpy, python-dateutil, pytz, tzdata

Syntax

PyUtils.PipShow, Package, /FILES, OUTPUT=variable, /VERBOSE

Arguments

Package

A string giving the name of the package.

Keywords

FILES

Set this keyword to output a list of the files within the package.

OUTPUT

By default, this method prints out the information to the IDL console. If the OUTPUT keyword is set to a named variable then the output will be returned in that variable instead.

Note: If an error occurs, IDL will halt execution and print the error message to the IDL console, regardless of the OUTPUT keyword.

VERBOSE

Set this keyword to produce additional output.

PyUtils::GetCurrentPython

The PyUtils::GetCurrentPython static method retrieves the version number and optional information about the currently running Python.

Example

IDL> >>>2+2
IDL> help, PyUtils.GetCurrentPython(info)
<Expression>    STRING    = '313'
IDL> info
{
  "PATH": "C:\Program Files\NV5\IDL92\bin\bin.x86_64\idl-python313\python.exe",
  "VERSION": "3.13.2",
  "SHORT_VERSION": "3.13",
  "EMBEDDED": true
}

Syntax

Result = PyUtils.GetCurrentPython(Info)

Return Value

Returns a string giving the version number (with no dots) of the Python that is active in the current IDL session. If Python is not running then a null string is returned.

Arguments

Info

If the optional Info argument is present, then it will be set equal to an IDL dictionary containing additional information about the running Python. This dictionary will have the following fields:

Key

Description
PATH The full path to the Python executable
VERSION The Python version, including major, minor, and subminor
SHORT_VERSION The Python version, including major and minor
EMBEDDED A boolean indicating whether this is the IDL embedded Python

Keywords

None

Version History

9.2

Introduced

See Also

IDL to Python, Installation - IDL to Python Bridge