IDAPython Environment

IDA embeds a Python interpreter for scripts and plugins. The interpreter, the packages installed in its environment, and the way IDA finds them all depend on how Python is configured on your system. This page explains the recommended setup and how to get there.

Why use a virtual environment

Without a virtual environment, IDA uses the system Python directly. This causes problems:

• On recent Linux distributions (Ubuntu 24.04+, Debian) and some macOS configurations, the system Python is marked externally managed (PEP 668). pip refuses to install packages into it.

• System Pythons often require administrator privileges to install packages.

• Packages installed globally can conflict with OS-managed packages.

A virtual environment gives IDA its own isolated set of packages. Plugins install their dependencies there without affecting the rest of the system.

Recommended setup

The recommended configuration has four parts:

1. A virtual environment at $IDAUSR/venv (typically ~/.idapro/venv on Linux and macOS, %APPDATA%\Hex-Rays\IDA Pro\venv on Windows).

2. The virtual environment has pip available.

3. The IDAPYTHON_VENV_EXECUTABLE environment variable points to the virtual environment's Python interpreter.

4. The virtual environment's Python version (major.minor) matches the libpython that idapyswitch registered for IDA.

When all four conditions hold, IDA and tools like HCLI can find and use the correct Python without guesswork.

IDA checks these conditions at startup and warns about any that are not met. If you have an existing setup that works and you understand its trade-offs, you can suppress the check by starting IDA with --no-python-environment-check. This is not recommended for new installations.

Setting up with HCLI

If you use HCLI to install IDA, add --create-python-environment to the install command:

hcli ida install \
    --download-id ida-pro:latest \
    --set-default \
    --create-python-environment \
    --accept-eula \
    --yes

This creates a virtual environment at $IDAUSR/venv and configures IDAPYTHON_VENV_EXECUTABLE.

To create the environment after IDA is already installed:

hcli ida python create-environment

The command detects which Python version IDA uses, creates the virtual environment with pip, and shows the shell command to set IDAPYTHON_VENV_EXECUTABLE. You can accept or apply it yourself.

Setting up manually

If you do not use HCLI, create the virtual environment yourself.

macOS / Linux

First, determine the Python version IDA expects. Run idapyswitch (in your IDA installation directory) to see the registered libpython. If IDA registered libpython3.12, create the virtual environment with Python 3.12.

With uv (includes pip automatically):

uv venv --seed --python 3.12 ~/.idapro/venv

Or with the standard library:

python3.12 -m venv ~/.idapro/venv

Then set the environment variable in your shell profile (e.g. ~/.zshrc, ~/.bashrc):

export IDAPYTHON_VENV_EXECUTABLE="$HOME/.idapro/venv/bin/python"

On macOS, shell profile variables do not apply to IDA started from Finder or the Dock. To set the variable system-wide:

launchctl setenv IDAPYTHON_VENV_EXECUTABLE "$HOME/.idapro/venv/bin/python"

Or start IDA from a terminal where the variable is set.

Windows

First, determine the Python version IDA expects. Run idapyswitch.exe (in your IDA installation directory) to check the registered library. If IDA registered python312.dll, create the virtual environment with Python 3.12.

python -m venv "%APPDATA%\Hex-Rays\IDA Pro\venv"

Then set the environment variable permanently:

setx IDAPYTHON_VENV_EXECUTABLE "%APPDATA%\Hex-Rays\IDA Pro\venv\Scripts\python.exe"

Restart IDA and any open terminals for the variable to take effect.

Key concepts

idapyswitch

The idapyswitch utility ships with IDA. It selects which Python shared library (libpython3.X) IDA loads at startup. Run it from your IDA installation directory to see or change the registered Python.

The venv must use the same Python version (major.minor) that idapyswitch registered. For example, if idapyswitch registered libpython3.12, the venv must use Python 3.12. A mismatch can cause subtle problems: native Python packages compiled for one version may crash or fail to import on another, while pure-Python packages may appear to work fine. This makes version mismatches a source of hard-to-diagnose bugs.

IDAPYTHON_VENV_EXECUTABLE

This environment variable tells IDA which virtual environment to use, regardless of how IDA is started: from a terminal, from the Dock or Start Menu, or by opening a file. It is the most reliable way to connect IDA to a virtual environment.

Other approaches (activating a venv in your shell before starting IDA, or adding activation code to idapythonrc.py) only work in specific launch scenarios. Desktop shortcuts, file associations, and system launchers do not carry shell activation.

idapythonrc.py

The file idapythonrc.py in your IDA user directory ($IDAUSR) runs immediately after IDAPython initializes. You can use it to import modules, configure settings, or run startup code.

• Windows: %APPDATA%\Hex-Rays\IDA Pro\idapythonrc.py

• Linux / macOS: ~/.idapro/idapythonrc.py

Some online guides suggest adding virtual environment activation code to idapythonrc.py. While this works for interactive IDA sessions, it does not reliably work in batch mode or when tools probe IDA's Python configuration. Use IDAPYTHON_VENV_EXECUTABLE instead.

See the IDAPython examples for a sample idapythonrc.py.

IDAPYTHON.CFG

The IDAPYTHON.CFG configuration file controls IDAPython settings. IDA looks for it in %IDADIR%/cfg and then in %IDAUSR%/cfg. See the comments inside the file for available options.

Installing packages

To install Python packages into IDA's environment, use the virtual environment's interpreter:

macOS / Linux

~/.idapro/venv/bin/python -m pip install <package>

Windows

"%APPDATA%\Hex-Rays\IDA Pro\venv\Scripts\python.exe" -m pip install <package>

If you use HCLI, you can also run:

hcli ida python exec -m pip install <package>

Plugins distributed through the Plugin Manager declare their dependencies in ida-plugin.json. HCLI installs these automatically when you install a plugin.

Verifying the setup

HCLI provides a diagnostic command:

hcli ida python doctor

This reports which IDA installation and Python interpreter it found, whether a virtual environment is present, whether pip is available, and whether the Python version matches. It lists any problems with suggested fixes.

Troubleshooting

"externally-managed-environment" error

The system Python is marked as externally managed (PEP 668). Create a virtual environment as described above. Do not remove the EXTERNALLY-MANAGED marker file.

pip is not available

The virtual environment was created without pip. Recreate it with uv venv --seed or python3 -m venv (which includes pip by default). If you used uv venv without --seed, add pip with:

~/.idapro/venv/bin/python -m ensurepip

Python version mismatch

The venv uses a different Python version than what idapyswitch registered for IDA. Recreate the venv with the correct Python version, or run idapyswitch to register the version that matches your venv.

IDA does not see installed packages

Check that IDAPYTHON_VENV_EXECUTABLE is set and points to the correct interpreter. Verify that you installed packages into the venv rather than the system Python. If you set the variable in your shell profile, make sure IDA was started from a session where it applies (or use launchctl setenv on macOS / setx on Windows).

Plugin installation fails

If hcli plugin install fails with a Python error, run hcli ida python doctor to diagnose the environment. The most common causes are a missing virtual environment, missing pip, or a version mismatch.

Suppressing the startup check

If you have a working Python setup that does not follow the recommended layout (for example, a conda environment or a custom sys.path configuration), IDA's startup check may warn on every launch. You can suppress it:

ida64 --no-python-environment-check

The check exists to catch common misconfiguration before it causes hard-to-diagnose failures. Only suppress it if you are confident your setup is correct.