transparent-background has a nightly mode that changes without notice, and a small image bug it works around

Three modes, one of them deprecated, one of them changeable without notice

The options section is the most valuable thing in the file, because it records three layers of history.

The oldest layer is a TorchScript flag. The file explains that it was widely used to disable dynamic resizing so the output was stable, that it was never meant to be used that way, and that a resize option was added as the honest replacement. The default is the static mode, described as giving a less detailed prediction in exchange for stability. The dynamic mode, which was the previous default, gives a more detailed prediction and is less stable.

The second layer is a deprecation. A news entry from September 2023 says a separately hosted checkpoint became available under a named mode, that the old fast argument is deprecated, and that the mode argument should be used instead. The mode argument takes three values: a base mode, the fast mode, and the base nightly mode.

The third layer is the sentence to keep in front of you. The nightly checkpoint, the file says, can be changed without any notice.

So of three selectable modes, one is deprecated, one is documented as unstable in a different way, and one can change under you. Any pipeline that needs identical output across runs has to pin the mode explicitly and record the checkpoint it used.

Layer four is a bug. The first news entry states plainly that the package is not working properly on small images without the fast argument, apologises, and promises a better algorithm later.

The dependency table lists eight packages and the manifest requires thirteen

The readme has a table of dependencies with a minimum version column. Count it and you get eight: a deep learning framework and its vision extension, an image library, a model library, a progress bar, an augmentation library, a download helper, and an optional virtual camera library.

The manifest asks for thirteen.

The five that never appear in the readme table are a download helper, a dictionary helper, a YAML parser, an image augmentation library, and a matting library.

The last two are the substantive omissions. An augmentation library at a recent floor suggests preprocessing that the readme never mentions, and a matting library is the thing that produces a soft edge on hair and fur. If you were choosing this package for hair matting, the readme gives you no reason to think the capability is there.

The floors are also worth a look, because they are old. The deep learning framework's minimum is 1.7.1 and the vision extension's is 0.8.2. Those are permissive rather than wrong: nothing stops you installing a current version. But it means the floor tells you nothing about which versions were actually tested, so you are the compatibility test.

The manifest also declares Python 3.8 and newer, and the classifier list is three lines long: a Python 3 marker, the licence, and an operating system marker.

Every documented install command pins the older CUDA wheel index

GPU support is handled by pointing pip at the framework vendor's wheel index instead of the default one, and the file gives two of them: one for CUDA 11.8 and one for CUDA 12.8.

Here is the problem. Four install commands are printed, and all four of them carry the 11.8 index:

pip install --extra-index-url https://download.pytorch.org/whl/cu118 transparent-background # install with official pytorch

That is the plain install, and the webcam, gui and from-GitHub variants repeat it. The 12.8 index appears only inside a note, formatted as a bare fragment.

So anyone who copies a command gets the older CUDA build, and anyone on a 12.8 driver has to notice the note and edit the URL by hand. The note does say the extra index is needed if you want to use a GPU and calls out Windows in particular, so the requirement is stated; it is the four copy-pasteable lines that disagree with it.

There is also a from-local option that clones the repository and installs from the checkout, cut off mid command in the printed file.

The three extras are consistent across the manifest and the readme: a virtual camera library for the webcam mode, a desktop GUI library, and nothing else. Which brings up the next section, because one of those extras was created by force.

The GUI dependency was moved out of the core after an import error

The notice section explains one packaging decision in more detail than anything else in the file, and the reason is worth knowing if you maintain dependencies yourself.

The GUI library was moved to an optional extra. Two reasons are given. The GUI mode is not used by most active users, and keeping it in the core was causing an import error for the latest version of that library.

So the sequence is plain: a third party library released a version that broke, the import happened at module load, and every user of the package hit it regardless of whether they wanted a GUI. The fix was to take the library out of the mandatory set and gate it behind an extra.

That is the right fix, and it has a consequence the file does not spell out. There are two console scripts registered: one for the command line tool and one for the GUI. Both are installed in every environment. So the GUI entry point exists on your machine whether or not you asked for it, and it will fail at import unless the extra is also installed.

Which means `transparent-background-gui` is a command that appears in a fresh install and does not run until you do a second install. The extras syntax to fix it is in the file.

Webcam is documented for three platforms and supported on one

The webcam path is where the documentation and the support statement diverge most visibly.

The file gives installation instructions for three operating systems. For Linux there is a kernel module to build and install, a module load step, and a command to create the virtual device. For Windows there is one line: install the virtual camera from the open source broadcasting project. For macOS there is a four step sequence, install the same tool, start its virtual camera, stop it, close it, and the heading itself is marked not stable.

Then the note under the dependency table says that, because of the backend workflow for the other two systems, only Linux is supported for webcam input.

And the install section labels the webcam extra not stable as well. A news entry from October 2023 says webcam support is not stable, that the dependency was removed from the default install for the latest release, and that the extra is available if you want it.

So: a feature with three sets of platform instructions, one of which is marked unstable in its own heading, an extra labelled unstable, a news entry calling it unstable, and a support statement that rules out two of the three platforms. The Linux instructions are the only ones the project stands behind, and they require a kernel module built from source and loaded with root privileges.

The fallback is stated too: if you do not install the virtual camera library, the tool visualises real-time output in a window instead. That is the path to use on the other two platforms.

Installing the package creates a directory in your home directory

The packaging script does something before it packages anything.

It reads the readme for the long description, then reads an environment variable naming a configuration path, defaulting to the expanded home directory of whoever is running it. It then creates a directory with a dotted name under that path, with exist_ok set so it does not care whether it is already there.

So building or installing this package writes to your home directory. Not into a virtual environment, not into a temporary build directory: into your home, by default, whether or not you ever run the tool.

That is unusual, and it has two practical consequences. In a container or a restricted build environment, an install that has a writable home but a read-only package prefix can fail at a point that looks unrelated to permissions. And if you install as one user and run as another, the configuration directory belongs to whoever installed it.

The environment variable is the intended control, so you can point it somewhere else, but nothing in the readme mentions this behaviour at all. It is only visible if you read the packaging script.

The rest of the manifest is ordinary: the package is listed with three module paths, package data is included, and the long description is taken straight from the readme.

Half a million downloads, then five million, and no release since 2025

The news section doubles as an adoption record, and it is worth reading as one.

In September 2024 the file announces that the package passed half a million downloads and ranked just under six thousand on a public list of top packages, and thanks its users. In July 2026 it announces five million downloads.

So the count went up by an order of magnitude in under two years. The badge at the top of the readme shows a live download figure, so the current number is higher still.

Against that, the release history is quiet. The newest release is 1.3.4 from May 2025, and the manifest still declares that version. So the code that is installed from the package index has not been released in well over a year, while downloads kept climbing.

And the last commit to the default branch is dated 8 July 2026, the same day as the milestone announcement. So the repository has been quiet for nearly three months, and the most recent change of any kind was the author marking his own counter.

The citation section is a short one and it matters for provenance. The package is credited to a paper from the Asian Conference on Computer Vision in 2022 on revisiting image pyramid structure for high resolution salient object detection, with pages given. The first author of that paper is the author of the package, and the model code lives under the same account.

So this is a first-party wrapper around the author's own model work, not a third party integration.

Editorial conclusion

transparent-background is worth using for batch image work where you control the environment and can pin a checkpoint, and it is a poor fit for a production pipeline that needs reproducible output without extra work. Three things to know before you build on it. The nightly mode is documented as changeable without any notice, so pin an explicit mode rather than taking the default behaviour. Small images are a known problem that the file admits to and works around with a separately hosted checkpoint rather than a code fix. And the dependency list you read is not the dependency list you install, because five packages in the manifest never appear in the readme table.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. plemeri/transparent-background on GitHub
4. README
5. Releases