How To Install UnifiedPlanning IO Python: Complete Setup Guide

Installing the UnifiedPlanning library from unifiedplanning.io in Python enables automated planning, classical planning, and temporal planning capabilities through a unified framework. This comprehensive guide details the environment configuration, pip installation commands, engine bindings management, and troubleshooting strategies required for a successful setup.

Pre-Operation Setup & Environment Requirements

Configuring an isolated development environment ensures that the UnifiedPlanning library and its extensive ecosystem of underlying engines do not conflict with existing global Python packages. UnifiedPlanning interacts with multiple external solver engines like PDDL parsers, Numeric planners, and Temporal engines, making a clean virtual environment mandatory.

• Essential tools and dependencies include Python version 3.8 or higher, pip package manager, virtualenv or conda for environment isolation, and a reliable C/C++ compiler toolchain if building specific underlying solver binaries from source distributions.
• Prerequisites require a foundational understanding of Python package management, virtual environments, automated planning paradigms, and command-line interface execution.
• Estimated installation duration is 10 to 15 minutes, with zero financial budget required as the core framework and many integrated engines are open-source and distributed under permissive licenses.

Step-by-Step Installation Procedure

Step 1: Create and Activate a Dedicated Virtual Environment

Open your terminal or command prompt and establish an isolated workspace to prevent package version collisions. Execute the virtual environment creation command using your primary Python executable by typing python -m venv up_env, replacing up_env with your preferred directory name. Activate the environment by running source up_env/bin/activate on macOS and Linux systems, or up_env\Scripts\activate on Windows command prompts. Ensure your command-line prompt updates to display the active environment name before proceeding to package installation.

Pro-Tip: Always verify your active Python version and architecture by running python --version and python -c "import platform; print(platform.architecture())" to ensure compatibility with compiled wheel distributions.

Step 2: Install the Core UnifiedPlanning Package via Pip

With the virtual environment active, update your package installer tools to the latest stable release by executing python -m pip install --upgrade pip setuptools wheel. Install the core unifiedplanning package by running pip install unifiedplanning. This core installation pulls in the necessary foundational Application Programming Interfaces, data structures, and the built-in sequential simulator necessary for defining problems, domains, actions, and fluents.

Warning: Avoid installing the package directly into the global system Python environment, as missing permissions or conflicting package dependencies from other machine learning or data science libraries can corrupt solver bindings.

Step 3: Install Essential Solver Engines and Bindings

UnifiedPlanning acts as an abstraction layer, meaning you must install specific planning engines to actually solve the formalized problems you construct in Python. Install the standard engines package, which bundles several prominent classical and temporal planners, by running pip install up-espp up-enhsp up-tamer or utilize the umbrella installation command for all natively supported engines if available via pip install unifiedplanning[engines]. Verify that the engine registries successfully populate by launching an interactive Python session and importing the framework.

Step 4: Verify the Installation and Test Engine Execution

Validate your installation by running a quick diagnostic script inside Python to confirm that both the core framework and the external solver engines are operational. Launch the Python interpreter and execute code that imports the unifiedplanning library, creates a small problem instance with a fluent, an action, and an initial state, and attempts to solve it using an available engine like ENHSP or Tamer. Check that the planner returns a valid plan object containing sequential or temporal actions without throwing engine-not-found exceptions.

UnifiedPlanning Ecosystem Component Matrix

Common Installation Failures and Field Fixes

• Root Cause: Missing C/C++ compiler or build dependencies when pip attempts to compile source distributions for specific engines on Linux or Windows.
  
  
  • Actionable Fix: Install build-essential packages on Ubuntu/Debian using sudo apt-get install build-essential python3-dev, or install the Microsoft Visual C++ Build Tools on Windows before attempting pip installation.
• Root Cause: Python version incompatibility where legacy Python 3.7 or lower is invoked by default in the terminal environment.
  
  
  • Actionable Fix: Explicitly invoke Python 3.8 or newer by using python3.10 -m venv up_env or python3.11 -m pip install unifiedplanning to target the correct binary interpreter.
• Root Cause: Solver binary execution permission errors on Unix-based systems preventing downloaded planner binaries from executing.
  
  
  • Actionable Fix: Navigate to the site-packages directory where the engines are installed and grant execution permissions to the underlying binaries using the chmod +x command on the relevant executable files.

Frequently Asked Questions

What Python versions are supported by UnifiedPlanning?

UnifiedPlanning officially supports Python versions 3.8, 3.9, 3.10, 3.11, and 3.12. Using Python 3.10 or newer is recommended to take advantage of modern type hinting improvements and optimal performance in underlying graph search algorithms.

Do I need external solvers to use UnifiedPlanning?

While the core package includes basic data structures, problem builders, and a sequential simulator, you do need external solver engines to automatically solve planning problems. Installing engine packages like up-fast-downward or up-enhsp provides the necessary computational backends.

Can I run UnifiedPlanning inside a Jupyter Notebook?

Yes, UnifiedPlanning operates seamlessly inside Jupyter Notebooks and JupyterLab environments. Ensure you install the package within the specific kernel associated with your notebook environment by running the pip install commands in a notebook cell prefixed with an exclamation point.

How do I check which planning engines are currently available?

You can programmatically inspect available engines in your Python environment by importing unifiedplanning.environment and querying the engine registry. Running get_environment().factory.engines will output a comprehensive dictionary of all currently installed and registered solver backends.

Why does pip throw a dependency resolution error during installation?

Dependency conflicts usually arise when older versions of numpy, networkx, or setuptools are already present in the environment. Resolve this by creating a fresh virtual environment and upgrading pip, setuptools, and wheel prior to installing the unifiedplanning package.

Start Automating Your Planning Problems Today

Deploy UnifiedPlanning in your Python environment now to streamline automated planning, domain modeling, and solver integration for your intelligent systems. Follow the installation steps above to configure your engines and begin building robust automated planning solutions.