USD in a Python VirtualEnv

Python and virtualenv

For the purposes of this tutorial, we are going to assume that all our work is going to happen in $HOME/usd-sandbox. We are also going to set an environment variable indicating the root of your virtual env. You can name it as you wish, here's one possibility.

CMake

Before you start, make sure that cmake 3.12 or newer are installed on your machine, and active in your path. You can verify it by typing cmake --version.

Python

Building USD in a virtualenv is most robust when the installation is completely self-contained and does not rely on globally available resources, such as a system installation of Python. A good way to achieve this is to install a version of Python in a non-global place, using an installer from python.org. Install virtualenv:

A virtualenv for USD

You will need to create a virtualenv once, and you will subsequently activate it whenever you wish use that environment for development or running usd tools.

Create the virtual env

I suggest naming the virtual env something like usd-20.05-env. Create it as follows:

Activate the virtual env

Activate it on mac or linux using the activate script.

Typing which python should allow you to verify that the python in use is within the usd-20.05-env directory hierarchy. In our case, $USDVENV/bin/python. Whenever you need to leave this environment you can either close your shell, or source the deactivate script, i.e. $USDVENV/bin/deactivate.

Windows is similar, except there are batch files.

Add missing pieces of the virtualenv

After your virtual environment is created, verify that the following files exist.

Depending on the phase of the moon, include and lib may be nested one layer deeper, in a directory indicating python version such as +---/python27. "Phase of the moon" means that the implementation details change underfoot frequently, so it's always necessary to double check.

If the files are not there, you will need to copy them manually into those locations.

USD Python prerequisites

pip

It is possible that pip is not functional in the virtualenv for reasons outside of your control. To test this, cd $USDVENV/bin and type pip. If pip isn't recognized as a command, we need to install pip into the environment. You may need to sudo.

After this step, running pip should succeed.

Pythonic Prerequisites

Install USD's pythonic preferences into the active virtual environment. Note that by default, pip will install packages in the virtualenv, in a location that the virtual env cannot actually see them without creating .pth files. Let's avoid that issue, and instruct pip to install the packages into the site-packages folder. If you are using Python 2.7, this will look like this:

Double check $USDVENV/lib/python2.7/site-packages to verify that PySide2, shiboken, and PyOpenGL actually landed there. If they didn't please file an issue on usd-build-club.

Clone USD

Ensure you are on the branch you wish to work with. For example, if you are working in the dev branch:

Build

Now that the environment has been created, set up, activated, and cloned, build USD:

Run usdview

When the dust settles, you are almost done. Set PATH and PYTHONPATH as instructed by the build output.

Issues

These steps have been shown to work on MacOS and Windows, but not yet on Linux. See this issue: https://github.com/PixarAnimationStudios/USD/issues/1162