> For the complete documentation index, see [llms.txt](https://docs.pending.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pending.ai/getting-started/installation.md). # Installation Access to the different Pending AI services is made available through a variety of different tools. Integrations are defined at different software layers to make installation more streamlined. Depending on your pipeline environment, there are many different available tools with more **under development** coming in [future releases.](#user-content-fn-1)[^1] All integrations leverage our API as the entry-point for the different Pending AI capabilities. *** ## Installing the CLI For creating simple scripts or interacting with the platform from your terminal {% hint style="info" %} **Prerequisites**: Install Python 3.9 or later (latest recommended). See [here](https://www.python.org/downloads/) for more information. Create a [Pending AI account](http://lab.pending.ai/) with access to the different services. {% endhint %} ### 1. Create a Python Environment (Recommended) The CLI tool is made available via the Python [PyPI](https://pypi.org/project/pendingai/) repository and can be installed using your favourite dependency manager. Before installing the tool, it's **recommended** to set up a clean environment to avoid dependency conflicts with cheminformatics libraries like `rdkit`.
Setting up a venv runtime Python's built-in `venv` module is the simplest way to get started with virtual environments. **1. Create a Virtual Environment:** Navigate to your project directory and run the following command. This creates a new directory (`.venv`) containing the Python interpreter and newly added libraries. ``` # For macOS / Linux python3 -m venv .venv # For Windows py -m venv .venv ``` **2. Activate the Environment:** Before you can use it, you need to activate the environment. ```bash # For macOS / Linux (bash/zsh) source .venv/bin/activate # For Windows (Command Prompt) .venv\Scripts\activate.bat # For Windows (PowerShell) .venv\Scripts\Activate.ps1 ``` You'll know the environment is active because the terminal prompt will change to show the environment name (e.g. `(.venv) Computer-Name:~ $`).
Setting up a conda runtime (Recommended) If you use the [Anaconda](https://www.anaconda.com/distribution/) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) distribution, `conda` is your go-to tool for environment management. It's particularly powerful for managing complex cheminformatics packages. **1. Create a Conda Environment:** This command creates a new environment named `pendingai-env` with a specific Python version. ```bash conda create --name pendingai-env python=3.13 ``` **2. Activate the Environment:** Before you can use it, you need to activate the environment. ```bash conda activate pendingai-env ``` You'll know the environment is active because the terminal prompt will change to show the environment name (e.g. `(pendingai-env) Computer-Name:~ $`).
### 2. Installation Methods Once your environment is active, you can install the `pendingai` tool. Here are some common methods. {% tabs %} {% tab title="pip" %} #### Using `pip` (Standard) `pip` is Python's standard package installer and is included with most Python installations. It's perfect for installing tools as part of a specific project's dependencies regardless of runtime. ```bash pip install pendingai ``` **To install a specific version:** ```bash pip install pendingai==0.4.0 ``` The tool is continually being improved, to **upgrade an existing installed version:** ```bash pip install --upgrade pendingai ``` {% endtab %} {% tab title="uv" %} #### Using uv (Recommended for performance) [uv](https://github.com/astral-sh/uv) is an extremely fast Python package installer and resolver. If you value speed, you can use it within any activated virtual environment (`venv` or `conda`). **Install `uv`:** ```bash pip install uv ``` **Install packages using `uv` similar to `pip`:** ```bash uv pip install pendingai # Latest uv pip install pendingai==0.4.0 # Specific version ``` **Note:** `uv` can install into activated virtual environments and requires running tools such as `pendingai` prefixing commands with `uv run `: ```bash uv run pendingai ``` {% endtab %} {% tab title="poetry" %} #### Using `poetry` (Recommended for projects) A modern Python project and dependency manager like [poetry](https://python-poetry.org/) can streamline version management in larger software projects. **Install `poetry`:** ```bash pip install poetry ``` **Install packages with `poetry`:** ```bash poetry add pendingai # Add as a main dependency poetry add -G pendingai # Add to a dependency group poetry add pendingai==0.4.0 # Specific version ``` **Note:** `poetry` installs into the Python environment automatically but it is recommended to invoke commands prefixed with `poetry run ` which is important for reproducibility: ```bash poetry run pendingai ``` {% endtab %} {% tab title="pipx" %} #### Using `pipx` (Recommended for global dependency management) The [pipx](https://github.com/pypa/pipx) tool is ideal for installing dependencies into the global Python runtime to be used across different virtual environments making it easier for use in different projects. **Install `pipx`:** ```bash pip install pipx pipx ensurepath ``` **Install packages with `pipx`:** ```bash pipx install pendingai ``` {% endtab %} {% endtabs %} ### 3. Verifying Your Installation Check the installation was successful by checking CLI is available in your terminal. ```bash pendingai --help pendingai --version ``` #### Authentication We provide a simple authentication flow from the CLI that will automatically redirect you to our login page. Multiple commands are provided to help manage the access control when using the different Pending AI services. ```bash pendingai auth login # Login to the Pending AI platform pendingai auth refresh # Refresh an authenticated session ``` ## Installing the SDK Pending AI currently supports a Python-based SDK available to install following the same steps as the CLI tool as both are bundled in the same package. Verify your installation with a simple script that sets up an authenticated client and lists our Retrosynthesis engines that are available for use: {% code lineNumbers="true" %} ```python from pendingai import PendingAiClient pai = PendingAiClient() # Create the client pai.authentication.login() # Login to the platform # Retrieve all retrosynthesis engines for engine in pai.retrosynthesis.engines.list(): print(f"Engine ID: {engine.id}") ``` {% endcode %} #### Authentication The SDK mimics the same authentication flow as the CLI tool but from a Python script. Cached active sessions can be used without any additional code after logging in from executing a script. To maintain the active session, it needs to be routinely refreshed, otherwise you will be redirect to login again. {% code lineNumbers="true" %} ```python from pendingai import PendingAiClient pai = PendingAiClient() pai.authentication.login() # Initially calling a script must login pai.authentication.refresh() # Repeated scripts can refresh a session ``` {% endcode %} ## Troubleshooting {% hint style="success" %} Have a specialised use case? Contact us at `support@pending.ai` for help with building custom pipelines. {% endhint %} Here are some common questions and how to resolve them.
Q: I installed a tool, but my terminal says command not found. What's wrong? A: This issues generally means your shell can't find the tool you just installed. Here are a few troubleshooting steps to try: * **Is your virtual environment active?** If you used `pip`, `uv`, or `conda`, your terminal prompt should have a prefix like `(.venv)` or `(pendingai-env)`. If it doesn't, you just need to reactivate it. Scroll up to the activation commands for `venv` or `conda`. * Does your project use a special runtime? Tools like `uv` and `poetry` have dependency resolvers that require an extra prefix before running a command, add `uv run` or `poetry run` to the start of your command. * **Did you just install `pipx`?** After running `pipx ensurepath`, you often need to open a brand new terminal window for the changes to your system's `PATH` to be applied. * **A handy workaround:** You can often run the tool directly as a Python module. For example, instead of running `pendingai --version`, you can type `python -m pendingai --version`. This can be a good temporary fix but a new Python environment is recommended.
Q: Why am I seeing a Permission denied error when I try to install something? A: This usually means you're trying to install a package into a protected system-wide directory without the right permissions (like using `pip` without `sudo`). The best solution is to **avoid using `sudo` with `pip`**. Doing so can cause issues with your operating system. Instead, stick to one of the methods as shown above: * Install inside a `venv` or `conda` environment. * Use `pipx` for global tools. These methods install packages in your user's home directory.
Q: The installation failed because of a dependency conflict. What does that mean? A: This happens when the tool you're installing needs a specific version of a package ( `rdkit==2025.3.5`), but another package has a conflicting requirement. It is recommended to use a new virtual environment or project-level dependency manager such as `poetry` to resolve this. * **Fix your environment:** Create a new, clean virtual environment using `venv` or `conda` and try installing the tool again. By isolating the tool and its dependencies, you give it a fresh start without any conflicting packages to worry about. * **Fix your project:** Within your project you can lock your dependencies (e.g. `poetry lock` or `uv lock`) and update the required packages to be compatible (likely by using the latest Python version). These tools guide you on how to resolve the conflicting packages.
Q: The tool installed, but it's crashing with a SyntaxError or another unexpected error. A: Our tool is under constant development and this may be the cause of new breaking changes. When invoking a command, a message is provided to upgrade your tool to the latest for out-of-date CLI usage. * **A quick fix:** Upgrade the package to the latest version using your chosen dependency manager (e.g. `pip install --upgrade pendingai`). * **Raise a ticket:** We are constantly improving our platform, let us know about this issue and how we could improve your journey using our solutions.
## Next Steps * See the different capabilities Pending AI offers to customers like [Retrosynthesis](/capabilities/retrosynthesis.md) or [Generative AI](/capabilities/generative-ai.md) * Follow one of our [Guides](/developer-tools/guides.md) to jump-start integrating our services into your Drug Discovery pipelines. * See our documentation for the [CLI](/developer-tools/cli.md) and [SDK](/developer-tools/sdks/python.md) for more information. [^1]: If you have any suggestions for more features or tools best suited for you, contact us as we look to create new integrations. --- # 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: ``` GET https://docs.pending.ai/getting-started/installation.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.