diff --git a/assets/macos_install.png b/assets/macos_install.png new file mode 100644 index 00000000..2cc1cfc5 Binary files /dev/null and b/assets/macos_install.png differ diff --git a/python/README.md b/python/README.md index df94185b..a2fb4cc2 100644 --- a/python/README.md +++ b/python/README.md @@ -18,6 +18,8 @@ most users who access MuJoCo through Python. For example, the `egl`, `glfw`, and ## Installation +### PyPI + The package can be installed from [PyPI](https://pypi.org/project/mujoco/) via ```sh @@ -27,15 +29,48 @@ pip install mujoco A copy of the MuJoCo library is provided as part of the package and does **not** need to be downloaded or installed separately. -If you wish to modify and build the bindings from source, you should clone the -entire `mujoco` repository from GitHub, then run the `make_sdist.sh` script to -generate a [source distribution](https://packaging.python.org/en/latest/glossary/#term-Source-Distribution-or-sdist) -tarball, then run `pip wheel name_of_sdist.tar.gz`. The `make_sdist.sh` script -generates additional C++ header files that are needed to build the bindings, -and also pulls in required files from elsewhere in the repository outside the -`python` directory into the sdist. +### Source -CMake and a C++17 compiler are needed to build the bindings from source. +**Note.** CMake and a C++17 compiler are needed to build the bindings from source. + +1. Download the [latest release](https://github.com/deepmind/mujoco/releases) from GitHub. On macOS, the download corresponds to a DMG file from which you can drag the `MuJoCo` app into your Applications folder. + +

+ +

+ +2. Clone the entire mujoco repository from Github and cd into the python directory. + +```bash +git clone https://github.com/deepmind/mujoco.git +cd mujoco/python +``` + +3. Create a virtual environment, for example with conda. + +```bash +conda create -n mujoco python=3.8 +conda activate mujoco +``` + +4. Generate a [source distribution](https://packaging.python.org/en/latest/glossary/#term-Source-Distribution-or-sdist) +tarball with the `make_sdist.sh` script. + +```bash +cd python +bash make_sdist.sh +``` + +The `make_sdist.sh` script generates additional C++ header files that are needed to build the bindings, and also pulls in required files from elsewhere in the repository outside the `python` directory into the sdist. Upon completion, the script will create a `dist` directory with a `mujoco-2.1.X.tar.gz` file (where X is the version number of the release). + +5. Install the generated tarball. You'll need to specify the path to the MuJoCo library you downloaded earlier. For example, on macOS, this will be `/Applications/MuJoCo.app/Contents/Frameworks/MuJoCo.framework` if you dragged it to your Applications folder. + +```bash +cd dist +MUJOCO_PATH=/PATH/TO/MUJOCO pip install mujoco-2.1.X.tar.gz +``` + +The python bindings should now be installed! To check that they've been successfully installed, cd outside of the mujoco directory and run `python -c "import mujoco"`. ## Usage diff --git a/python/make_sdist.sh b/python/make_sdist.sh index d422ed68..424f07b4 100755 --- a/python/make_sdist.sh +++ b/python/make_sdist.sh @@ -13,7 +13,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -if [[ -z ${VIRTUAL_ENV} ]]; then +if [[ -z ${VIRTUAL_ENV} ]] && [[ -z ${CONDA_DEFAULT_ENV} ]] ; then echo "This script must be run from within a Python virtual environment" exit 1 fi @@ -28,7 +28,7 @@ else readonly tmp_dir="$(mktemp -d)" fi -python -m pip install --upgrade pip +python -m pip install --upgrade pip setuptools wheel python -m pip install absl-py pushd ${tmp_dir} cp -r "${package_dir}"/* .