Use the Legacy pysetup Interface Safely on Python Systems

You will learn how to recognise the legacy pysetup interface, inspect a project before changing the system, and choose a safer route when the command is absent. Allow about 15 minutes. You need a shell, a Python project or package name to investigate, and permission to read its files. Installation and removal can change shared Python state, so do not start with those actions on a production host.

The local manual is unusually specific about its age. The file is named pysetup3.12, but its content identifies the command as pysetup3.3, version 3.3, dated January 2012. The installed Ubuntu package here is python3.12 version 3.12.3-1ubuntu0.17. Those are different facts: a Python 3.12 package does not prove that this historical command is installed.

1. Check which command you actually have

Start by checking the executable and the package metadata. These commands only read the system:

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

On the machine described by this guide, the second command reports python3.12 3.12.3-1ubuntu0.17, but none of the three command names resolves. The installed manual page is therefore reference material, not evidence that an executable is available.

Checkpoint: if command -v prints a path, run the matching program with --version before doing anything else:

$ pysetup --version
pysetup3.3 3.3

The exact version and output belong to the executable on your host. Do not substitute python3.12 for pysetup; they are not interchangeable commands.

2. Understand the action model

The manual describes one command followed by an action. The available actions are run, metadata, install, remove, search, list, graph, create and generate-setup:

$ pysetup [options] action [action_options]

This is a project-management interface, not a general Python interpreter. The action-specific syntax is deliberately not expanded by the short manual page. Ask the installed program for that action's help before copying an example from an old system:

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

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

3. Inspect before installing

Use the read-oriented actions first. Replace the example name with a real project identifier only after checking the action help:

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

The manual says that search searches package indexes, metadata displays project metadata, list lists installed projects, and graph displays a graph. It does not define the index configuration, output format or project argument in this short page. Consequently, treat each command's own --help output as authoritative for that installation.

Do not put credentials, private index URLs or real internal package names into a public transcript. Index access can disclose project names even when it does not install anything.

4. Make a proposed change observable

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 change between commands.

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

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

Checkpoint: record the dry-run output and the exact project name. If it proposes writes outside the intended environment, stop. Do not continue merely because the command returned to the shell.

5. Separate user and elevated operations

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

$ pysetup install EXAMPLE_PROJECT

If the command reports a permission error, first confirm that a user-local installation is supported by its action 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 is selected. Never use sudo to work around an unknown index, dependency or destination.

Removal is destructive to the environment. Before running it, capture the installed list and test whether another application imports the project:

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

If removal causes a problem, the undo is to reinstall the same known project version using the project's documented source. There is no rollback command described by this manpage, so preserve the dry-run output and any package metadata before removing anything.

6. Use the remaining utility actions carefully

create can create a project, and generate-setup can generate a backward-compatible setup.py. Both write files. Run their action-specific help first and choose an empty, disposable directory:

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

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