> For the complete documentation index, see [llms.txt](https://docs.hex-rays.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hex-rays.com/getting-started/idapython-environment.md).

# 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](https://hcli.docs.hex-rays.com/) 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](https://hcli.docs.hex-rays.com/) to install IDA, add `--create-python-environment` to the install command:

```bash
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:

```bash
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.

{% tabs %}
{% tab title="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](https://github.com/astral-sh/uv) (includes pip automatically):

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

Or with the standard library:

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

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

```bash
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:

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

Or start IDA from a terminal where the variable is set.
{% endtab %}

{% tab title="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.

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

Then set the environment variable permanently:

```powershell
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.
{% endtab %}
{% endtabs %}

## 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`

{% hint style="info" %}
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.
{% endhint %}

See the [IDAPython examples](/developer/idapython/idapython-examples.md#idapythonrc) for a sample `idapythonrc.py`.

### IDAPYTHON.CFG

The [`IDAPYTHON.CFG`](/core/user-interface/concepts/configuration-files.md) 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:

{% tabs %}
{% tab title="macOS / Linux" %}

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

{% endtab %}

{% tab title="Windows" %}

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

{% endtab %}
{% endtabs %}

If you use HCLI, you can also run:

```bash
hcli ida python exec -m pip install <package>
```

Plugins distributed through the [Plugin Manager](https://plugins.hex-rays.com/) declare their dependencies in `ida-plugin.json`. HCLI installs these automatically when you install a plugin.

## Verifying the setup

HCLI provides a diagnostic command:

```bash
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:

```bash
~/.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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hex-rays.com/getting-started/idapython-environment.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.