Installation via pipx fails due to PyCG dependency

[whitequark]

I'd really like to try out the package! However, there is no first-party Docker image (I don't want to build my own for a tool I'm not familiar with yet); I don't really want to use Docker anyway, but unfortunately pipx, which is the recommended way to install Python CLI tools, doesn't work either:

$ pipx install pytrim
installed package pytrim 0.1.2, installed using Python 3.13.5
These apps are now globally available
- pytrim
- trim
done! ✨ 🌟 ✨
$ pytrim amaranth/
Generating call graph: 0it [00:00, ?it/s]PyCG is not installed. Install it with:
git clone https://github.com/gdrosos/PyCG.git
cd PyCG
pip3 install .
export PATH="$HOME/.local/bin:$PATH"
Generating call graph: 0it [00:01, ?it/s]

I suspect that declaring PyCG as a dependency will resolve this, but I haven't dug into the source yet.

[whitequark]

Ah, I didn't realize that PyCG is another command-line application that pytrim depends on. Indeed, declaring it as a dependency should work, but there are further issues. First, it depends on the deprecated pkg_resources module which isn't present in Python 3.13 and requires obsolete setuptools:

$ pipx install git+https://github.com/gdrosos/PyCG.git
installed package PyCG 0.0.8, installed using Python 3.13.5
These apps are now globally available
- pycg
done! ✨ 🌟 ✨
$ pipx inject PyCG 'setuptools<81'
injected package setuptools into venv PyCG
done! ✨ 🌟 ✨

Even with this, pytrim doesn't work:

$ pytrim amaranth/
Generating call graph: 0it [00:00, ?it/s]Creating virtual environment...
Processing rfc3986 (1/5)...
Processing Jinja2 (2/5)...
Processing jschon (3/5)...
Processing pyvcd (4/5)...
Processing MarkupSafe (5/5)...

Call graph file /home/whitequark/Projects/amaranth/amaranth/call_graph_data/cg.json does not exist.
Generating call graph: 200it [00:08, 24.91it/s]
Cleaning up temporary files: 100it [00:00, 610524.60it/s]
Traceback (most recent call last):
File "/home/whitequark/.local/bin/pytrim", line 7, in <module>
sys.exit(main())
~~~~^^
File "/home/whitequark/.local/share/pipx/venvs/pytrim/lib/python3.13/site-packages/pytrim/cli/cli.py", line 278, in main
if "" in libraries_to_process:
^^^^^^^^^^^^^^^^^^^^^^^^^^
TypeError: argument of type 'NoneType' is not iterable

I tried running PyCG manually (I have no insight into whether this is the right or the wrong way to run it) and it crashed:

$ pycg amaranth/
/home/whitequark/.local/share/pipx/venvs/pycg/lib/python3.13/site-packages/pycg/formats/fasten.py:23: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
from pkg_resources import Requirement
Traceback (most recent call last):
File "/home/whitequark/.local/bin/pycg", line 7, in <module>
sys.exit(main())
~~~~^^
File "/home/whitequark/.local/share/pipx/venvs/pycg/lib/python3.13/site-packages/pycg/__main__.py", line 62, in main
cg.analyze()
~~~~~~~~~~^^
File "/home/whitequark/.local/share/pipx/venvs/pycg/lib/python3.13/site-packages/pycg/pycg.py", line 180, in analyze
self.do_pass(
~~~~~~~~~~~~^
PreProcessor,
^^^^^^^^^^^^^
...<5 lines>...
self.module_manager,
^^^^^^^^^^^^^^^^^^^^
)
^
File "/home/whitequark/.local/share/pipx/venvs/pycg/lib/python3.13/site-packages/pycg/pycg.py", line 159, in do_pass
self.import_manager.install_hooks()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
File "/home/whitequark/.local/share/pipx/venvs/pycg/lib/python3.13/site-packages/pycg/machinery/imports.py", line 225, in install_hooks
self._clear_caches()
~~~~~~~~~~~~~~~~~~^^
File "/home/whitequark/.local/share/pipx/venvs/pycg/lib/python3.13/site-packages/pycg/machinery/imports.py", line 95, in _clear_caches
importlib.invalidate_caches()
~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
File "/usr/lib/python3.13/importlib/__init__.py", line 68, in invalidate_caches
finder.invalidate_caches()
~~~~~~~~~~~~~~~~~~~~~~~~^^
File "<frozen importlib._bootstrap_external>", line 1484, in invalidate_caches
File "/usr/lib/python3.13/importlib/metadata/__init__.py", line 21, in <module>
from . import _meta
File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
File "<frozen importlib._bootstrap>", line 1322, in _find_and_load_unlocked
File "<frozen importlib._bootstrap>", line 1262, in _find_spec
File "<frozen importlib._bootstrap_external>", line 1559, in find_spec
File "<frozen importlib._bootstrap_external>", line 1533, in _get_spec
File "<frozen importlib._bootstrap_external>", line 1666, in find_spec
File "<frozen importlib._bootstrap_external>", line 1620, in _get_spec
File "/home/whitequark/.local/share/pipx/venvs/pycg/lib/python3.13/site-packages/pycg/machinery/imports.py", line 41, in __init__
ig_obj.create_edge(self.fullname)
~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^
File "/home/whitequark/.local/share/pipx/venvs/pycg/lib/python3.13/site-packages/pycg/machinery/imports.py", line 90, in create_edge
raise ImportManagerError("Can't add edge to a non existing node")
pycg.machinery.imports.ImportManagerError: Can't add edge to a non existing node

[k-karakatsanis]

Hi, thank you for this very detailed and valuable feedback!

You've arrived at the perfect time. We are in the middle of preparing a significant new release, which we expect to publish in the next couple of days. This new version will fix the TypeError you discovered and include many other improvements.

For now, the best and most reliable way to use the tool is with the pre-built Docker image, which has the correct version of PyCG and all its dependencies configured. Here is the link:

https://hub.docker.com/r/karakatsanis/pytrim

I'll post another update here as soon as the new release is live. Thanks again for taking the time to write this up!

[whitequark]

How do you actually run it against code that's not inside Docker using this image?

[k-karakatsanis]

You have to use a volume mount (-v) to link your local code folder to the /project folder inside the container.

The easiest way is to first cd into your project's root directory:

cd /path/to/your/project

Then, run this command:

For Linux/macOS:

docker run --rm -it -v "$(pwd):/project" karakatsanis/pytrim

For Windows (PowerShell):

docker run --rm -it -v "${PWD}:/project" karakatsanis/pytrim

The $(pwd) part (or ${PWD} on Windows) automatically uses your current directory.

The docker run command drops you into a shell inside the /project directory, where your code is mounted.
To analyze the entire project in the current directory, just run:

pytrim

As a reminder, the new release coming in the next couple of days will include many improvements and should provide a much smoother experience overall.

[k-karakatsanis]

Following up on my previous messages, the new release, v0.2.0, is now live!

It addresses all the excellent points you raised. You can get it now by running pip install --upgrade pytrim or by pulling the new :latest Docker image.

To summarize the key improvements based on your feedback:

• We've significantly updated the README with clearer Docker instructions and have highlighted the more stable, alternative detectors like FawltyDeps and deptry.
• We've also added a fall-back mechanism in case PyCG fails during analysis.

Thank you again for this incredibly valuable report!

I'm going to close this issue now, but please feel free to comment again if you find the problem persists, and we can reopen it.

[whitequark]

Unfortunately it looks like the new-user experience is still not ideal:

$ pipx install pytrim
installed package pytrim 0.2.0, installed using Python 3.13.5
These apps are now globally available
- pytrim
- trim
done! ✨ 🌟 ✨
$ pytrim
Analyzing project dependencies...

Call graph file /home/whitequark/Projects/amaranth/call_graph_data/cg.json does not exist.
Traceback (most recent call last):
File "/home/whitequark/.local/bin/pytrim", line 7, in <module>
sys.exit(main())
~~~~^^
File "/home/whitequark/.local/share/pipx/venvs/pytrim/lib/python3.13/site-packages/pytrim/cli/cli.py", line 443, in main
if libraries_to_process is not None and "" in libraries_to_process:
^^^^^^^^^^^^^^^^^^^^^^^^^^
TypeError: argument of type 'Exception' is not iterable

[whitequark]

Also if I don't have PyCG installed it suggests I install it, which is inconsistent with you saying that other callgraph detectors being more stable (and thus, I assume, preferred?)

$ pytrim
Analyzing project dependencies...
PyCG is not installed. Install it with:
git clone https://github.com/gdrosos/PyCG.git
cd PyCG
pip3 install .
export PATH="$HOME/.local/bin:$PATH"

[whitequark]

• We've significantly updated the README with clearer Docker instructions and have highlighted the more stable, alternative detectors like FawltyDeps and deptry.

Actually I don't see any mention of fawltydeps or deptry in README anywhere except the CLI option list (which doesn't seem like it's being highlighted); did you push the README update?

[whitequark]

I have confirmed that after pipx install pytrim fawltydeps deptry I have got pytrim to work without using Docker. However, while testing (I changed the code to make some dependencies unused), I encountered this output:

$ pytrim -dp
Analyzing project dependencies...
Error running deptry: Command '['/tmp/tmpnpgsyw66/deptry_venv/bin/python', '-m', 'pip', 'install', '.']' returned non-zero exit status 1.

I'm genuinely unsure what's causing this (pytrim -fd works fine), but the bigger problem is that your tool is swallowing the output of a subcommand. It should capture and display it so I can actually fix the problem, or at least report it sensibly.

[karyotakisg]

Hi @whitequark, when installing pytrim you have to manually install pycg, because we don't use a pycg version from a package registry but from a Github repository instead. For tool isolation, please consider using Docker.