Investigate the Legacy pysetup Command Before Using It

The manpage called pysetup3.12 is misleading: it documents pysetup3.3, a project tool from January 2012, and it might not even be installed. Give this about 15 minutes. You need a shell, a Python project or package name to investigate, and permission to read its files.

• Do not start with install or remove. Those actions can change shared Python state, so save them until you have confirmed what you are actually running.
• The installed Ubuntu package here is python3.12 version 3.12.3-1ubuntu0.17. That is a separate fact from whether the historical pysetup command exists: a Python 3.12 package proves nothing either way.

1. Check which command you actually have

These two commands only read the system, so run them first:

$ command -v pysetup3.12 pysetup3.3 pysetup
$ dpkg-query -W -f='${Package} ${Version}\n' python3.12

On the machine this guide was written on, the second command reports python3.12 3.12.3-1ubuntu0.17, but none of the three names in the first command resolves. The installed manpage is reference material here, not evidence that an executable is available.

$ pysetup --version
pysetup3.3 3.3

Use the exact version and output from your own host. Do not substitute python3.12 for pysetup; they are not interchangeable commands.

2. Learn the action model

The manual describes one command followed by an action:

$ pysetup [options] action [action_options]

The available actions are run, metadata, install, remove, search, list, graph, create and generate-setup. This is a project-management interface, not a general Python interpreter, and the short manpage does not expand each action's own syntax. Ask the installed program directly before copying an example from an old system:

$ pysetup metadata --help
$ pysetup install --help
$ pysetup remove --help

If the executable is missing, you cannot run these locally, and that is a useful result rather than a reason to guess the options. The historical design around static project metadata was discussed in PEP 390, which was later rejected. Treat this as legacy tooling and check the project's current packaging instructions before adopting it.

3. Inspect before you install anything

Use the read-oriented actions first, and only put in a real project name once you have checked that action's own help:

$ pysetup search EXAMPLE_PROJECT
$ pysetup metadata EXAMPLE_PROJECT
$ pysetup list
$ pysetup graph EXAMPLE_PROJECT

• search searches package indexes.
• metadata displays project metadata.
• list lists installed projects.
• graph displays a dependency graph.

The short manpage does not define the index configuration, output format or project argument for any of them, so treat each command's own --help output as authoritative for your installation.

4. Make a proposed change observable first

The global --dry-run option tells pysetup not to do the operation. Pair it with the action you are considering, and keep the verbose default while investigating:

$ pysetup --dry-run --verbose install EXAMPLE_PROJECT

The manual defines --dry-run as "don't actually do anything" and --verbose as the default mode. A dry run is a safety check, not proof that a later real install will succeed: indexes, files, permissions and dependencies can all change between commands.

For a quiet script or a deliberately small transcript, use --quiet instead:

$ pysetup --dry-run --quiet install EXAMPLE_PROJECT

5. Keep elevated operations separate

Installing or removing a project may write to a shared interpreter, site-packages directory, or another administrator-controlled location. The manual promises no privilege model, so start without elevation:

$ pysetup install EXAMPLE_PROJECT

If that reports a permission error, confirm first that a user-local install is supported by the action's own help and the project's documentation. Only then consider an explicitly approved administrator operation:

$ sudo pysetup install EXAMPLE_PROJECT

Read the complete plan before accepting it. sudo changes who can write, not what package gets selected. Never use it to work around an unknown index, dependency or destination.

$ pysetup list
$ python3.12 -c 'import EXAMPLE_MODULE; print(EXAMPLE_MODULE.__file__)'
$ pysetup --dry-run remove EXAMPLE_PROJECT

6. Use the remaining actions carefully

create can create a project, and generate-setup can generate a backward-compatible setup.py. Both write files, so run their own help first and work in an empty, disposable directory:

$ mkdir -p ~/tmp/pysetup-example
$ cd ~/tmp/pysetup-example
$ pysetup create --help
$ pysetup generate-setup --help

These examples only change directory contents once an action is actually invoked. To undo an unwanted generated file, remove that specific file after inspecting it rather than deleting the whole directory; the manual does not document the generated file's contents or overwrite rules.