How to Install the Python Package for Project Aria Tools
This page provides information about how to install the Python utilities using a virtual environment or from source. We recommend that only advanced users install from source.
Go to the Python Type Annotation page for how to enable type hinting.
Install via virtual environment
Step 1 : Install Python
To use projectaria_tools and its Jupyter notebooks, you'll need Python 3.9 or above (3.10 if you are on Apple Silicon or Windows). To ensure all utilities work effectively, we recommend keeping Python 3 up to date.
- Python 3 download page
- To check what what version of Python 3 you have use
python3 --version
Step 2 : Create a virtual environment
- Linux & macOS
- Windows
rm -rf $HOME/projectaria_tools_python_env
python3 -m venv $HOME/projectaria_tools_python_env
source $HOME/projectaria_tools_python_env/bin/activate
Remove-Item $HOME\projectaria_tools_python_env
py -3 -m venv $HOME\projectaria_tools_python_env
& $HOME\projectaria_tools_python_env\Scripts\Activate.ps1
Step 3 : Install the required Python packages
python3 -m pip install --upgrade pip
python3 -m pip install projectaria-tools'[all]'
Step 4 : Use Project Aria Tools
A few resources are:
- Getting Started with Project Aria Data Utilities - Python Tutorial
- Request Machine Perception Services - for Research Partners
Check the Python module import error section of Data Utilities Troubleshooting Guide if you encounter this issue
Building Python bindings from source (advanced user)
You'll need to install C++ dependencies to build Python bindings from source.
- Go to the C++ Installation page and follow the instructions to install dependencies
- Go to the projectaria_tools code folder
- Enter the following commands
cd $HOME/Documents/projectaria_sandbox/projectaria_tools
python3 -m pip install --upgrade pip
python3 -m pip install .
For multithread build use the following:
CMAKE_BUILD_PARALLEL_LEVEL=4 pip3 install .
If you encounter error during the build process like ERROR: No matching distribution found for library X
:
- Double check that you are using the right pip, or Python version and then use
python -m pip install .
orpython3 -m pip install .
Generate and install type hinting from source (advanced user)
- Install pybind11-stubgen to generate the stub files
- Generate Python type hinting with generate_stubs.py script once projectaria_tools package is installed
- Install type hinting package for projectaria_tools
python3 -m pip install pybind11-stubgen==1.1
cd $HOME/Documents/projectaria_sandbox/projectaria_tools
python3 generate_stubs.py
cp -r projectaria_tools-stubs/projectaria_tools .
python3 -m pip install .
Building Python bindings from source with a package manager
You can build projectaria_tools python bindings in isolation using pixi on and for your local platform (Linux, macOS Intel/Silicon, Windows) using the exact same command lines. Pixi is a convenient package and environment manager that simplifies the logic to compile and run projects by defining dependencies and tasks in a single pixi.toml file for all platforms.
For Windows platform we assume that Microsoft Visual C++ Compiler, MSVC 2017 or 2022 has been installed.
Step1 Install Pixi
- Linux & macOS
- Windows
# Install Pixi
curl -fsSL https://pixi.sh/install.sh | bash
# Install Pixi
iwr -useb https://pixi.sh/install.ps1 | iex
Step2 Compile and test the code
# When this command line first run, it will collect required dependencies, and then trigger the build and unit test
pixi run run_python
Step3 Access the compiled artifacts
# Activate the environment
pixi shell
# You can now run and use things from the projects
python
import projectaria_tools
dir(projectaria_tools)
# Will print
>>>['__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__path__', '__spec__', 'core']