Installation

Requirements

• Python 3.9 - 3.11 only
• FFmpeg
• ImageMagick
• (Recommended) Ubuntu 22.04 or Windows 10

Quick start

pip install ezsam
sudo apt install ffmpeg imagemagick
ezsam --help
ezsam-gui

Standard installation

pip install ezsam

For video output, you need to install FFmpeg and have it available on your $PATH as ffmpeg for all the encoding options except GIF.

GIF output requires ImageMagick; convert must be available on your $PATH.

# For apt-based Linuxes like Ubuntu, Debian...
sudo apt install ffmpeg imagemagick

If you're having trouble, see Troubleshooting.

Binary installation

The gui app (only) has a compiled executable release.

1. Still install FFmpeg and/or ImageMagick as in Standard installation
2. (Optional) See here about "standalone" vs "one-file" releases
3. Download a release
4. Extract anywhere and run

Warning

On Windows, you might have to fix the executable's permissions to allow it to run:

1. Right click release folder or onefile executable → Properties → Security → Advanced
2. Check "Replace all child object permissions...", if it's the release folder
3. Select first entry "Deny Everyone Traverse folder & execute" → Remove this Deny permission

Troubleshooting

General

Thanks to pytorch, and the general state of python package management, you might have run into installation issues.

Here's some pointers to try and help:

• Setup and use a dedicated version of python that's not your system python, using for example pyenv
• Use pipx to install in a separate environment: pipx install ezsam
• Try a Development install, which uses locked dependencies in a virtual environment by default

If you really want to get things working:

• See if you can run similar tools: rembg, Segment Anything, Grounded Segment Anything
• Check the project's Issues
• Use a CUDA 12.1 capable GPU with NVIDIA's official drivers and set $CUDA_HOME
• Try running the project from an Ubuntu 22.04 install or docker image

Windows

Just in case it helps.... Here's a list of potential issues Windows 10 users might run into trying to install Python and ezsam from scratch, and one example (non-exhaustive) solution for each:

1. Installer from python.org can't be executed, even as Administrator. You've already checksummed the installer and checked its permissions.
   • Workaround: Install Python 3.11 from the Microsoft Store
2. Microsoft Store Python 3.11 can't create virtual environment (using python -m venv .venv)
   • Workaround: Don't create virtual environment
3. Installation (i.e. pip install ezsam) fails without support for long paths
   • Workaround: https://pip.pypa.io/warnings/enable-long-paths
4. After installation, ezsam is not on the system PATH
   • Workaround: Add Microsoft Store python's scripts folder to your user PATH:
     1. Search bar → Edit the system environment variables
     2. Click Environment Variables
     3. User variables for <username> → Select and edit Path
     4. Add new variable, for example (replacing with your user AppData install location): C:\Users\<username>\AppData\Local\Packages\ PythonSoftwareFoundation.Python.3.11_xxxxxxx\LocalCache\local-packages\Python311\Scripts

Your mileage may vary. Good luck!