.. _isaac_sim_app_install_python:

========================================================
Python Environment Installation
========================================================

It is possible to run |isaac-sim_short| natively from Python rather than as a standalone executable. 
This provides more low-level control over how to initialize, setup, and manage an |omni| application. 

.. _isaac_sim_install_python_default:

Default Python Environment
===================================================

|isaac-sim_short| provides a built-in Python 3.7 environment that packages can use, similar to a
system-level Python install. We recommend using this Python environment when running the Python
scripts.

Run the following from the |isaac-sim_short| root folder to start a Python script in this
environment:

    .. code-block:: bash
        
        ./python.sh path/to/script.py

.. note::
    - You can open a terminal directly at the |isaac-sim_short| root folder from the :ref:`isaac_sim_app_selector`.
    - If you need to install additional packages via *pip*, run the following:

        .. code-block:: bash

            ./python.sh -m pip install name_of_package_here

.. note::
    - On windows use python.bat instead of python.sh

.. seealso:: 
    See the :ref:`isaac_sim_python_environment` manual for more details about ``python.sh``. 

.. _isaac_sim_install_python_jupyter_notebook:

Jupyter Notebook Setup
=======================

Jupyter Notebooks that use |isaac-sim_short| can be executed as follows:

    .. code-block:: bash

        ./jupyter_notebook.sh path/to/notebook.ipynb

.. note::
    - The first time you run ``jupyter_notebook.sh``, it will install the Jupyter Notebook package
      into the |isaac-sim_short| Python environment, this may take several minutes.

.. note::
    - Currently, Jupyter notebook is supported on Linux only.

.. seealso:: 
    See the :ref:`isaac_sim_python_jupyter_notebook` documentation for more details. 

.. _isaac_sim_install_python_vscode:

Visual Studio Code Support
===================================

The |isaac-sim_short| package provides a ``.vscode`` workspace with a pre-configured environment
that provides the following:

- Launch configurations for running in standalone Python mode, or the interactive GUI
- An environment for Python auto-complete

You can open this workspace by opening the main |isaac-sim_short| package folder in Visual Studio
Code (VSCode). 

.. note::
    Using Visual Studio Code when going through tutorials and examples is recommended. 

.. seealso:: 
    See the :ref:`isaac_sim_python_vscode` documentation for details about the VSCode workspace. 

.. _isaac_sim_install_python_docker:

Advanced: Running In Docker
=======================================

Start the Docker container following the instructions in :ref:`isaac_sim_setup_remote_headless_container`
up to step 8.

Once the |isaac-sim_short| container is running, you can run a Python script or Jupiter Notebook
from the sections above.

.. note::
    - You can install additional packages via *pip*:

      .. code-block:: bash

         ./python.sh -m pip install name_of_package_here
    
    - See :ref:`isaac_sim_save_docker_image` for commiting the image and making the Python setup
      installation persistent.

.. _isaac_sim_install_python_anaconda:

Advanced: Running with Anaconda
======================================

Create a new environment with the following command:

    .. code-block:: bash

        conda env create -f environment.yml
        conda activate isaac-sim

If you have an existing conda environment, ensure that the packages in ``environment.yml`` are
installed. Alternatively, you can delete and re-create your conda environment as follows:

    .. code-block:: bash

        conda remove --name isaac-sim --all
        conda env create -f environment.yml
        conda activate isaac-sim

Finally, you need to set up environment variables so that |isaac-sim_short| python packages are
located correctly.  On Linux, you can do this as follows:

    .. code-block:: bash

        source setup_conda_env.sh

You can then run samples as follows in the ``isaac-sim`` conda env:

    .. code-block:: python

        python path/to/script.py

.. note::
    If you are using the ``isaac-sim`` Anaconda environment, use ``python`` instead of ``python.sh``
    to run the samples.