Skip to content

FDP on macOS

On an Apple Silicon Mac (M1 and later) FDP installs natively, the same way as on Linux: every package in the blessed set has an Apple Silicon build. On an Intel Mac it runs the Linux environment inside a container instead; see Intel Macs below.

Apple Silicon: native install

1. Install fdp

pixi global install -c ga-fdp -c conda-forge fdp-installer   # or conda
fdp-install -d ~/fdp

fdp-install writes ~/fdp/pixi.toml for your Mac and runs pixi install. The conda method works on Apple Silicon too.

2. Log in and run

cd ~/fdp && pixi shell         # activates the environment
fdp login                      # prints a URL; open it in any browser
fdp run python my_script.py

From here everything on the Basic Usage page applies unchanged: fdp ls, TokSearch pipelines, Jupyter, IDEs pointed at ~/fdp/.pixi/envs/default/bin/python.

What is different from Linux

  • fdp-core 1.35.0 or newer. That is the first release with an Apple Silicon build of every package; fdp-install --core-version with an older version stops with an error.
  • No --with-labeler. ga-dfl-labeler is Linux-only.
  • The DIII-D database snapshot needs the internet on first use. connect_d3drdb() reads the snapshot with DuckDB's httpfs extension. On a Mac it is downloaded from DuckDB's extension server the first time and cached under ~/.duckdb; its signature is checked. On Linux it ships with the environment.

Intel Macs: the container

There is no native Intel Mac build, so fdp-install installs an fdp command that runs each invocation inside the FDP container image, with your current directory mounted. fdp login, fdp run python script.py and fdp ls are the same text as on Linux. On Apple Silicon, fdp-install --container gives you the same setup if you prefer it.

1. Install a container runtime

Either of these open runtimes works. Docker Desktop and OrbStack also work but are licensed products and are not what we test.

Podman (recommended):

brew install podman
podman machine init --cpus 4 --memory 8192
podman machine start

Colima (keeps the docker command):

brew install colima docker
colima start --cpu 4 --memory 8

On Apple Silicon with --container, the image is x86-64 and runs under Rosetta: Podman turns it on by default, and Colima needs --vm-type=vz --vz-rosetta. The fdp command warns if it finds Rosetta off.

2. Install fdp

pixi global install -c ga-fdp -c conda-forge fdp-installer   # or conda
fdp-install -d ~/fdp              # add --container on Apple Silicon
export PATH="$HOME/fdp/bin:$PATH"  # add to your shell profile

fdp-install pulls the image for the current release (a few GB, once) and writes ~/fdp/bin/fdp. To pin a release: fdp-install --core-version X.Y.Z.

3. Log in and run

fdp login                      # prints a URL; open it in any browser
fdp run python my_script.py    # runs inside the environment
fdp shell                      # an interactive shell inside it

What is different from Linux

  • Your current directory is visible inside the environment at the same path, and so is the folder of any file under your home directory that you name on the command line (read-only). Files under /tmp, /usr or other system paths are not. Keep scripts and outputs under the directory you run from, and do not run fdp from /.
  • fdp env prints a message instead of exports. Nothing on the Mac itself can import toksearch; run things through fdp run.
  • IDEs and Jupyter attach to the container, not to a local Python.
  • Parallel pipelines (compute_multiprocessing, Ray) see the VM's CPUs and memory, not the Mac's; the machine init lines above give it 4 CPUs and 8 GB, which the demo pipelines need.
  • Login state lives in ~/.fdp and ~/.config/pelican on the Mac and is reused across runs; a token lasts 24 hours.
  • Not for ARM Linux machines: there the same image runs under QEMU and is far too slow.

Troubleshooting

  • fdp: no container runtime found on PATH: install Podman or Colima (above) and start the machine. FDP_CONTAINER_RUNTIME=podman|docker|container picks one explicitly.
  • pull failed ... If the container machine is not running: podman machine start or colima start, then re-run fdp-install.
  • A warning about Rosetta being disabled: recreate the Podman machine with podman machine init --rosetta=true.
  • permission denied on ~/.fdp inside the container: the directory was created by the runtime as root. sudo chown -R $USER ~/.fdp ~/.config/pelican and retry.
  • Running the Podman machine rootful (podman machine init --rootful) is not supported; fdp relies on the rootless user mapping.