Appendix D: Setup Troubleshooting

Most setup problems come down to one question: which Python, and which shapescript, is running? So start by asking, in the terminal where the problem happens:

python -c "import sys; print(sys.executable)"
which -a python shapescript

python -c "import sys; print(sys.executable)"
type -a python shapescript

python -c "import sys; print(sys.executable)"
Get-Command python, shapescript -All

With the environment active, the first one listed is in your project’s .venv. The rest of this appendix is the usual problems, roughly in the order you’d meet them in Chapter 1.

Building from source

These come up only if you build ShapeScript yourself (Chapter 1, Building from source).

linker 'cc' not found, or link.exe not found

Rust needs a C linker. On macOS, xcode-select --install; on Debian and Ubuntu, sudo apt install build-essential; on Fedora, sudo dnf install gcc; on Windows, Microsoft’s C++ build tools (Chapter 1 has the winget command).

rustc 1.xx is not supported

ShapeScript needs Rust 1.88 or later. Run rustup update.

cargo: command not found

Open a new terminal: rustup changed the PATH of new ones. In fish, run fish_add_path ~/.cargo/bin once.

Python and the virtual environment

Windows: Activate.ps1 cannot be loaded

PowerShell refuses to run scripts by default, and activating is a script. Allow your own and signed ones, for your user only:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Then activate again.

Windows: python opens the Microsoft Store

That’s Windows’ placeholder for a Python that isn’t installed, or isn’t on the PATH. Use the launcher, py -3.13, to make the environment; once it’s active, python is the environment’s.

python isn’t the environment’s, even though it’s active

Something put another Python ahead of .venv on your PATH: usually a version manager such as pyenv, asdf or mise that switches Python when you change folders, or conda’s base environment. Check with the commands at the top. Either turn the tool off for the project, or skip activation and name the environment’s programs by path: .venv/bin/python -m pip install ... (.venv\Scripts\python.exe on Windows).

Apple Silicon: Bad CPU type in executable, or incompatible architecture

The Python is an Intel (x86_64) one, and the programs you built are for Apple Silicon (arm64), or the other way round. Errors like mach-o file, but is an incompatible architecture (have 'arm64', need 'x86_64') on import shapescript, or pip finding no version of torch at all, are the same problem. Check:

python -c "import platform; print(platform.machine())"
uname -m

Both should print arm64. If Python prints x86_64, it’s an Intel Python, often from an old Homebrew in /usr/local: delete .venv and make it again with /opt/homebrew/bin/python3.13 -m venv .venv. If uname -m prints x86_64, your terminal runs under Rosetta: in Finder, open the terminal app’s Get Info and untick Open using Rosetta.

pip install shapescript: No matching distribution found

pip found no wheel of ShapeScript for this Python and platform. The wheels are for Python 3.9 or later on Linux (x86_64 and aarch64, with glibc 2.28 or later), macOS (Apple Silicon on macOS 11 or later, Intel on 10.12 or later) and Windows (x64). Check the Python with python --version and python -c "import platform; print(platform.machine())": an old Python, a 32-bit one, or an Intel Python on Apple Silicon is the usual cause (see the entry above). An old pip can miss the wheels too: python -m pip install --upgrade pip. On another platform, such as Windows on Arm or Alpine Linux, build from source.

maturin: Both VIRTUAL_ENV and CONDA_PREFIX are set

conda’s base environment is active underneath your virtual environment, and maturin develop doesn’t know which to install into. Leave conda, then activate .venv again:

conda deactivate

Or, for this terminal only, unset conda’s variable:

unset CONDA_PREFIX

set -e CONDA_PREFIX

Remove-Item Env:CONDA_PREFIX

conda config --set auto_activate_base false stops conda from activating base in every new terminal. Or use pip install ~/shapescript/crates/py, which doesn’t mind conda.

this installation of shapescript has no shapescript binary

The package was built from source without the two programs. Copy them into the package (Chapter 1, Clone and build) and run pip install ~/shapescript/crates/py again. With maturin develop, the copy alone is enough.

shapescript: command not found

The environment isn’t active in this terminal, or ShapeScript isn’t installed in it. Activate it, and check with pip show shapescript.

shapescript run can’t find torch or shapescript

If shapescript run says No module named shapescript, or can’t import torch, it ran the wrong Python. shapescript run and shapescript export run Python: the environment’s own shapescript uses the environment’s Python; one installed with cargo install uses --python, else the SHAPESCRIPT_PYTHON environment variable, else python3. Pass --python .venv/bin/python, or set the variable:

export SHAPESCRIPT_PYTHON=~/hello-shapescript/.venv/bin/python

set -x SHAPESCRIPT_PYTHON ~/hello-shapescript/.venv/bin/python

$env:SHAPESCRIPT_PYTHON = "$HOME\hello-shapescript\.venv\Scripts\python.exe"

These last for the terminal. (In fish, set -Ux keeps it for good, and set -e SHAPESCRIPT_PYTHON removes it.)

pip install ./mypkg is slow, or fails without a network

pip builds a package in a fresh environment, with its build dependencies from PyPI: ShapeScript, and PyTorch with it, which is a large download, and impossible offline. Build it with your environment’s ShapeScript instead:

pip install hatchling
pip install --no-build-isolation ./mypkg

PyTorch

torch.cuda.is_available() is False on a machine with an NVIDIA GPU

Look at torch.__version__. If it ends in +cpu, you have the CPU build, the default on Windows: uninstall it and install the CUDA build with the command from pytorch.org’s selector:

pip uninstall -y torch

If PyTorch says The NVIDIA driver on your system is too old, the build needs a newer CUDA than your driver supports. nvidia-smi shows the newest CUDA version the driver supports, top right: pick a build no newer than that, or update the driver. In a notebook, restart the kernel after changing PyTorch.

UserWarning: Failed to initialize NumPy

PyTorch works without NumPy, but warns. pip install numpy.

The editor

The editor shows no errors or hovers

Go down this list:

1. The status bar, bottom right, should say ShapeScript when a .ss file is open. If it says Plain Text, the extension isn’t installed in this VS Code: code --list-extensions should list shapescript.shapescript. Reload the window after installing it.
2. If VS Code opened the folder in Restricted Mode, trust it (the banner at the top, or Workspaces: Manage Workspace Trust).
3. Open the Output panel (View › Output) and choose ShapeScript in its menu. An error there, or a notification saying couldn't start the language server, usually means a shapescript.server.path setting that names a file that doesn’t exist, or a .vsix for another platform (darwin-x64 on Apple Silicon, say). Fix or remove the setting, or uninstall the extension and install it again from the Marketplace, which picks your platform’s (or, if you build it, rebuild the .vsix for your platform).

ci/vsix.sh: warning: no dist/bin/…/shapescript-lsp, so no VSIX

The script found no language server for that platform. Build it first (cargo build --release -p shapescript-lsp), and name your own machine’s platform: the script packs target/release’s server only for the platform it was built on. On Windows, run the script in Git Bash.

Pylance: Import "torch" could not be resolved, or "shapescript"

VS Code is using another Python than your environment’s. Run Python: Select Interpreter and pick .venv, or set python.defaultInterpreterPath (Chapter 1, Select the environment’s Python). The status bar shows the selected one when a Python file is open.

Pylance: Import "hello" could not be resolved

There’s no hello.py beside hello.ss yet. The extension writes it when hello.ss is opened or saved without errors: fix its errors and save it. It writes none when the setting shapescript.pythonModules is off.

Debugging: debugpy isn’t found

The debugger comes with Microsoft’s Python extension. Without it, install it into the environment, pip install debugpy, and name the environment’s Python in the setting shapescript.debug.python.

Notebooks

%load_ext shapescript: No module named 'shapescript'

The kernel isn’t your environment’s Python. In VS Code, click the kernel’s name at the top right and pick .venv; in Jupyter in the browser, install jupyterlab into the environment and start it from there. import sys; sys.executable in a cell shows which Python the kernel is.

The kernel can’t start, or VS Code asks for ipykernel

The environment needs pip install ipykernel (VS Code offers to run it).