How projects, Python environments and saving work
This page explains the ideas behind the panels: what a project is, which Python runs your code, which editor draws it, and what actually protects your work.
A project is a folder, not a tab
A project is the folder you open. Its tree shows the files it contains, and its
settings live in a .pyeditor folder inside it, so they travel with the folder
and can be committed.
An editor tab is one open document, which is not always a file in that project: an example opened from Learn appears in a tab without becoming part of the project. The project also supplies the interpreter, the package environment and the run configurations, so the same script can behave differently in two projects.
The run configuration decides what the run button does. Current Selected File follows whatever you have selected; a named configuration always targets the script, arguments, environment variables and working directory saved in it.
An interpreter and a package environment are different things
The interpreter is the Python that runs your code. Packages are the libraries
that code imports. A project can have a perfectly good interpreter and still fail
on import, because the library is missing from that interpreter's environment.
Py Editor offers three interpreter modes in Project Settings → Interpreter:
- Embedded — the Python built into the app. It needs no setup and no Helper, and it is the right choice for scripts that only use the standard library.
- Project .venv — a virtual environment inside the project folder, created and filled through Helper. This is the mode for anything that needs third-party packages, because those packages belong to that one project.
- Custom — a Python you installed yourself. Py Editor validates the path and reports the version it found; the project also has to be compatible with it.
Creating the environment and installing what the project declares are two
separate steps, which is why a freshly created .venv can still report missing
dependencies.
Helper extends what the app is allowed to do
The app itself is sandboxed. Py Editor Helper is a separate signed component that runs as your user and does the work the sandbox forbids: creating virtual environments, using an external interpreter, installing packages, opening the Terminal and the Python Console, driving the debugger and the profiler, running Git, and reaching Docker and the cloud command-line tools.
Without Helper, Py Editor still edits code and runs dependency-free scripts with the embedded interpreter. With it, the interpreter mode decides which Python is used. "Helper is connected" says the component is available; it says nothing about whether a particular project is ready to run. The MCP server that lets a coding agent drive the app also lives in Helper and is switched on separately in Application Settings → MCP & Coding Agents.
Choose the surface that matches the task
| Surface | Use it when you want to… |
|---|---|
| Run | Execute the configured program and read its output. |
| Python Console | Execute a file, then inspect or change its objects in the same session. |
| Terminal | Enter shell commands in the project folder. |
| Debug | Pause at a breakpoint and step through the code. |
A Console expression changes the live session, not the file on disk. Clearing output and stopping a session are different actions: clearing leaves the objects in place, stopping discards them.
Two editor engines behind one editor
The editor comes in two engines, chosen in Application Settings → Editing: ACE, the default, and Native, a macOS text editor built on TextKit. Save your work before switching, because the change applies to every open window.
Both engines edit, complete, fold, comment and search, and the menu commands are the same in both. A few features exist only in the native engine: coverage colors in the gutter, conditional breakpoints, the run buttons beside test functions, and error underlining in the source. The Vim, Emacs, Sublime and VSCode keymaps apply only to ACE.
Saving, Local History and Git each protect something else
Saving writes the editor's text to the file. With Autosave When Switching Files on, moving to another file or closing a tab saves it for you; turn that setting off in Application Settings → Editing if you would rather be asked first. Either way, not saving is not a reliable way to discard an edit — undo it instead.
Reload From Disk goes the other way and replaces the editor's text with the file on disk. It is a refresh, not a merge: if another program changed the file, keep the version you care about somewhere else first.
Local History, on the editor tab's context menu, lists earlier saves of that file and shows how each one differs from the current text. It is a comparison view for recent work, not a backup system.
Git is separate again. A saved file is not a commit, and a commit is not a push. Creating a repository, committing and switching branches all happen on this Mac until you deliberately use a remote command.