Wingware
Creating a Project
Classic+
To create a new project, use New Project in the Project menu, or New Project... on the welcome screen. The New Project dialog is one page with a section for each part of the project: where its source directory is, which Python it uses, and how it is set up. Sections that do not apply to the choices made are hidden. Pressing Create Project creates the project, as described under Creating the Project below.
The source directory may be on the local host or a remote system. The Python environment may be a base Python install, a virtualenv, an environment managed by uv, Poetry, or pipenv, an Anaconda env, or a container environment managed by Docker, Docker Compose, Vagrant, or LXC/LXD. A new source directory can also be given a new Git or Mercurial repository, which can be published to GitHub.
Simple and All Options
The dialog has two modes. Simple shows only the common choices. All Options adds the less common ones, along with a list at the left of the sections, showing each one's current value. Clicking on a section in the list scrolls to it.
To switch modes, click All Options or Simple at the bottom of the dialog. Values set in All Options are kept when switching to Simple, even those it does not show. Wing remembers the mode last used, and the first time Wing starts it asks which mode to start with.
Working With, above the list of sections in All Options, sets some of the project's properties for a framework, library, or application that embeds Python. For example, Flask enables child process debugging so Flask's reload feature works with Wing's debugger, Django enables debugging of Django templates, and Scientific (Matplotlib) enables support for interactive plots. Simple always uses Python, and All Options starts with the one last used.
Source
The cards at the top of the dialog select where the project's source comes from:
New directory creates a new directory with the given Name in the directory set in Create In. The line under Create In shows the full path of the directory to be created. This is the default.
Existing directory uses the existing Source Directory selected. If it contains a virtualenv at its top level or in .venv or venv, or if it is managed by uv, Poetry, pipenv, or pixi, Wing says that it found the environment and selects it in the Python section, as described under Existing Environments below.
Clone repository clones a Git or Mercurial repository, selected from the popup menu in Repository, from the URL entered next to it. The clone goes into a new directory named with Directory Name in the directory set in Location, and the line under Location shows its full path. Directory Name follows the repository's name until another is entered. To pick one of your own Git repositories or those of your organizations on GitHub, press My GitHub Repositories... next to the URL. This lists the repositories, with a field to filter them, and Choose sets Repository to the one selected. If you are not signed in to GitHub, press Sign In to GitHub... there, as described under Signing In to GitHub below.
No directory creates an empty untitled project for configuring later with Add Existing Directory, Project Properties, and Save Project As in the Project menu. Wing offers to save it once it is created.
Host, under the cards, selects the host where your source directory will be located. The default is the local host. Any remote host, VM, or container that is accessible by ssh may also be used with Wing's remote development capability. To access a remote system for which you don't already have a remote host configuration, add one with Create Configuration... in the Host popup menu. Simple shows Host only once a remote host has been selected, so use All Options to select one.
If you are using containers, select Local Host, since the master copy of your source directory is stored locally. The containerized Python environment is selected or created in the Python section.
Python
This section selects or creates the Python environment for the project. Environment offers these choices:
New Env creates a new environment with the tool selected in Manager, under Environment: Virtualenv, uv, Poetry, pipenv, or Conda Env, and in All Options also Docker. Manager starts with the tool last used, and the first time with Virtualenv, which creates a virtualenv as .venv inside the project's source directory. See Creating Python Environments for the options for each kind of new environment.
Existing Env uses an existing virtualenv, Anaconda, micromamba, or pixi environment, which is activated each time the project runs Python, as described under Existing Environments below.
Existing Python runs an existing Python installation, or an environment's Python, as described under Existing Pythons below.
Container and Cluster, in All Options only, use an existing Python container or cluster of containers, as described under Containers and Clusters below.
Wing remembers the choice last made.
When uv, Poetry, or pipenv is chosen and is not installed, the section says so at once and offers to install it. See Creating Python Environments for details.
If you selected a remote host, Environment offers New Env and Use Remote Host Config, which causes Wing to use the Python that you selected when you set up your remote host configuration. In New Env, Python Executable lists the remote host's default Python first, then the Pythons found on the remote host's PATH. Environment also offers Existing Env when the existing directory selected under Source contains an environment, and then lists only that one. Docker and Conda Env are not offered on a remote host.
Existing Environments
In Existing Env, Activate lists the virtualenvs found on your system, the environments in each Anaconda installation found, and recently used environments, each under a heading. Virtualenvs that were moved or copied from where they were created are marked (moved). To use another environment, select Other: and enter the full path of the environment's directory or its Python, the full path of a virtualenv's activate or activate.bat script, or the command that activates an Anaconda environment.
Wing chooses how the project runs the environment from what it is. A virtualenv or Anaconda environment is set up as Activated Env with its activate command. A moved virtualenv, a pixi environment, and a micromamba environment are set up as Command Line: a moved virtualenv runs its own Python, a pixi environment runs through pixi run, and a micromamba environment through micromamba run, except on Windows. When the environment cannot be activated in full, the dialog shows a notice that says why and how to fix it. See How Projects Run Each Kind of Environment in Creating Python Environments for details.
When the existing directory selected under Source contains a virtualenv, a pixi environment, or an environment managed by uv, Poetry, or pipenv, Wing selects Existing Env and sets it to that environment, which is listed first under In the project directory. The project uses it only if it is still selected when you press Create Project. Choosing another source directory puts back the previous choice, unless you changed it.
An environment created by uv has no pip, so even when it is activated pip runs the next one on the PATH and installs into another Python. Use uv pip instead. The Packages tool does this for you.
Existing Pythons
In Existing Python, Python Executable lists the Python installations found on your system, with their versions, newest first, under Found on this computer. By default, it selects the Python found on the PATH, or if none is found there the latest version found anywhere on the system. Default Python, shown with the version it is now, instead makes this choice each time the project runs, so the project follows any later change to which Python that is. If no Pythons are found, the list offers only Default Python.
In All Options, the Python Envs submenu of Python Executable lists the virtualenvs found or recently used, including those marked (moved). Selecting one uses its Python.
Other: is used to select any other Python installation. You will need to enter the full path to the python, python3, or python.exe executable in the entry area shown next to it. This is the value of sys.executable after import sys in the Python you wish to use.
Wing also activates a virtualenv or Anaconda environment whose Python is selected in Existing Python, so its code and tools find the environment's own python, pip, and other scripts by name. See Python Executable in Project Properties for details.
For a new directory, Test Framework at the end of the section selects the unit testing framework to configure for the project. It is shown only in All Options, and the default is None.
Containers and Clusters
Container uses an existing Python container managed by Docker or LXC/LXD. You will need to select an existing container configuration or add a new one with the New button. Adding a new configuration here tells Wing how to use your existing container but does not create a new container environment. To create a new container environment, use New Env with Docker.
Cluster works in a similar way, but for clusters of Python containers managed by Docker Compose.
See Working with Containers and Clusters for more information on using containers and clusters in Wing.
Version Control
This section appears for a new directory. In Simple, Create a Git repository creates a new local Git repository in the new directory. It is checked by default when Git is installed. In All Options, Repository selects None, New Git, or New Mercurial.
Wing adds an ignore file to the new repository that leaves out Python's generated files, such as __pycache__, build output, and the .venv and venv virtualenvs, along with the project's .wpu file and its AI agent files. It then makes an initial commit of the project's files, including the ignore file, the project's .wpr file, and the AGENTS.md file it writes when setting up an AI agent. If Git or Mercurial does not yet have your user name and email, Wing first asks for them, as described for the Commit operation. If you press Cancel there, Wing still tries the commit, which fails with Git.
A new repository is not connected to any remote unless it is published to GitHub. For a new Git repository on the local host, checking Publish to GitHub creates a repository on GitHub after the initial commit and pushes to it. Name is the GitHub repository's name, which follows the project's name until another is entered, and Visibility makes it Private or Public. Private is the default. All Options also shows Owner, which selects your GitHub account or one of your organizations, and an optional Description. Checking Publish to GitHub asks you to sign in to GitHub, if you have not already.
Signing In to GitHub
Wing signs in to GitHub in one of three ways. If the GitHub CLI gh is installed and signed in, Wing uses its sign-in and asks for nothing. Otherwise, Wing shows the Sign In to GitHub dialog:
Sign In with Browser shows a code and opens GitHub's sign-in page in your web browser, with the code copied to the clipboard. Once you enter the code there and approve Wing's access, the dialog closes.
Use Token signs in with a GitHub personal access token pasted into the field above it. The token needs the repo and read:org scopes.
A sign-in from the dialog is kept in the OS's keychain: the login Keychain on macOS, Credential Manager on Windows, or the Secret Service on Linux, through secret-tool. Where there is no keychain, the sign-in lasts until Wing quits. Git uses the sign-in to clone and push, so no SSH key is needed. To sign out of a sign-in from the dialog, press Sign Out in the list shown by My GitHub Repositories....
AI Agent
Set Up for AI Agent configures the project for use with an AI coding agent: Claude Code, Codex, Antigravity, Copilot, Cursor, goose, OpenCode, or other agents that speak the Agent Client Protocol (ACP). This gives the agent access to Wing's debugger, test runner, and review system through MCP, making it work more efficiently, and supports the human user in managing AI-assisted development within Wing. See Using Wing with an AI Agent for details. Note that not all AI agents are equally safe or well suited to autonomous development. See the table in AI Agent Safety for details.
Wing runs each agent's own terminal interface inside the AI Agent tool, except for goose and other ACP agents, which Wing manages in its own AI agent conversation UI. The ACP versions of the other agents are listed only when the Show ACP Versions of Agents preference is enabled. See Setting Up an AI Agent for details.
All Options shows the rest of this section. Two options apply only once an agent is chosen, and both are checked by default, also in Simple. Autonomous Tasks Manager turns on the Tasks Manager, which runs Ready tasks for you and passes their questions on to you. Autonomous Commits commits work without waiting for you: with the Tasks Manager, each task is committed once its tests pass, and without it the agent commits at logical stopping points. Neither pushes to a remote repository. To change them later, use Task Scheduling and Commit Mode in Project Properties, or the Manager's Commits setting in the Tasks tool.
Debugging
Use wingdbstub for Debugging configures the project to start debugging with wingdbstub, rather than launching code from Wing. See Debugging Externally Launched Code for details. This option is shown only in All Options, and not for project types that always use wingdbstub.
Creating the Project
Pressing Create Project first checks the values entered. When uv, Poetry, or pipenv needs to be installed, Wing asks before installing it. On a remote host, Wing checks for it only at this point, and installs it without asking.
While the project is created, the dialog shows a checklist of the steps, with a spinner on the step running, and marks each step as it completes. Show Details under the step running shows its output. Cancel stops creating the project once the step running ends.
If a step fails, the checklist shows its output. Press Retry to run that step again, for example after fixing a network problem, and then continue with the rest. Press Close to stop there. The project is kept as far as it was created.
Section Contents