feat: (demo) allow users to use Pixi named workspaces through a registry

[soapy1]

Description

This implements a demo for the global registry of workspaces suggested in #4461.

Key changes

pixi workspace register command

This command looks like:

$ pixi workspace register -h                   
Commands to manage the registry of workspaces. Default command will add a new workspace

Usage: pixid workspace register [OPTIONS] [COMMAND]

Commands:
  list    List the registered workspaces [aliases: ls]
  remove  Remove a workspace from registry [aliases: rm]
  prune   Prune disassociated workspaces from registry [aliases: pr]
  help    Print this message or the help of the given subcommand(s)

Options:
  -n, --name <NAME>  Name of the workspace to register
  -p, --path <PATH>  Path to register

Global Options:
  -m, --manifest-path <MANIFEST_PATH>  The path to `pixi.toml`, `pyproject.toml`, or the workspace
                                       directory
  -w, --workspace <WORKSPACE>          Name of the workspace
  -h, --help                           Display help information
  -v, --verbose...                     Increase logging verbosity (-v for warnings, -vv for info, -vvv
                                       for debug, -vvvv for trace)
  -q, --quiet...                       Decrease logging verbosity (quiet mode)
      --color <COLOR>                  Whether the log needs to be colored [env: PIXI_COLOR=] [default:
                                       auto] [possible values: always, never, auto]
      --no-progress                    Hide all progress bars, always turned on if stderr is not a
                                       terminal [env: PIXI_NO_PROGRESS=]

It allows users to make an association between a path on disk and a name that represents the environment at that location. Users my create a new registry entry by running the commands:

# register the current workspace
$ pixi workspace register

# register the current workspace with a name
$ pixi workspace register -n myworkspace

# register a workspace at some manifest path
$ pixi workspace register -m /path/to/my/project

# register an arbitrary workspace
$ pixi workspace register -n myworkspace -p /path/to/my/project 

Cleaning up the registry of workspaces

Currently, this suggests 2 ways of being able to clean up registered workspaces:

• pixi clean (--workspaces-registry)
• pixi workspace register prune

These commands will remove any name/path association where the path no longer exists.

Further, users may remove an association using the pixi workspace remove command.

Creating new named workspaces

Users may create a new workspace that is automatically registered in the workspace registry by using the --workspace/-w argument in the pixi init command. For example

$ pixi init -w myproject

The original proposal suggests

Creating new named workspaces
Create $PIXI_HOME/workspaces/workspace and adds it to the named-workspaces
And adds the packages to the workspace and installs them.

Instead of creating new named workspaces in a central location, this demo suggests that when a new workspace is created with the --name argument, pixi should:

• create the workspace as it normally does; then
• register the name of the workspace to the requested init location.

Then, users can further customize the install location of their environment using the detached-environmnet configuration parameter.

Further investigation

It would be helpful to include a demo using:

• a default global workspace location
• file system and place symlinks, or a file with a path on platforms that don't support symlinks, to point to workspaces

Argument name

In this demo, the name of the argument to is workspace, shortcut to -w this is because name and -n are already used.

Other notes

Demo for #4461
If this is a direction that your team is interested in, I would be very excited to clean this demo up and write up some testing.

How Has This Been Tested?

Try out this demo:

Register an existing pixi project

# create a new pixi project
$ cd /tmp && mkdir test-one && cd test-one
$ pixi init
✔ Created /tmp/test-one/pixi.toml

# add some dependencies
$ pixi add python==3.11        
✔ Added python==3.11

# register environment
$ pixi workspace register
✔  Workspace registered successfully.

# list available registered environments
$ pixi registry list 
test-one = "/tmp/test-one"

Create a new named+registered environment

# create a new pixi project
$ cd /tmp && mkdir test-two && cd test-two
$ pixi init -w test-two     
✔ Created /tmp/test-two/pixi.toml

# check: the pixi.toml is still created in the current dir
$ ls   
pixi.toml

# check: the workspace has been registered
$ pixi workspace register list     
test-one = "/tmp/test-one"
test-two = "/tmp/test-two"

Use a named workspace

Using a name workspace acts in the same way as using the --manifest-path argument.

# the `--manifest-path` and `--workspace` arguments are mutually exclusive
$ pixi run --manifest-path /something --workspace something        
error: the argument '--manifest-path <MANIFEST_PATH>' cannot be used with '--workspace <WORKSPACE>'

Usage: pixid run --manifest-path <MANIFEST_PATH> [TASK]...

For more information, try '--help'.

# add some dependencies to our environment `test-two`
$ pixi add -w test-two python flask            
✔ Added python >=3.14.2,<3.15
✔ Added flask >=3.1.2,<4

# see that the environment has been updated
$ cat /tmp/test-two/pixi.toml     
[workspace]
authors = ["sophia <scastellarin@openteams.com>"]
channels = ["conda-forge"]
name = "test-two"
platforms = ["linux-64"]
version = "0.1.0"

[tasks]

[dependencies]
python = ">=3.14.2,<3.15"
flask = ">=3.1.2,<4"

# run python from the test-two environment
$ pixi run -w test-two -- python              
Python 3.14.2 | packaged by conda-forge | (main, Dec  6 2025, 11:21:58) [GCC 14.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import flask
>>> 

Use a named workspace with multiple environments

Consider a pixi.toml

[workspace]
authors = ["sophia <scastellarin@openteams.com>"]
channels = ["conda-forge"]
name = "test-three"
platforms = ["linux-64"]
version = "0.1.0"

[tasks]

[dependencies]
python = "*"

[feature.py310.dependencies]
python = "3.10.*"

[feature.py311.dependencies]
python = "3.11.*"

[environments]
py310 = ["py310"]
py311 = ["py311"]

Let's register the workspace and interact with the environments

# register the environment
$ pixi registry add test-three /tmp/test-three   
✔  Workspace registered successfully.

# check what python version is installed in each of the three environments
$ pixi run -w test-three -- python --version                                   
Python 3.14.2

$ pixi run -w test-three -e py310 -- python --version                      
Python 3.10.19

$ pixi run -w test-three -e py311 -- python --version                 
Python 3.11.14

Remove a workspace from the registry

# list existing workspaces
$ pixi workspace register list                                                         
test-three = "/tmp/test-three"
test-one = "/tmp/test-one"
test-two = "/tmp/test-two/pixi.toml"

# remove a workspace
$ pixi workspace register remove test-two                                                 
✔  Workspace 'test-two' has been removed from the registry successfully.

# observe test-two is no longer registered
$ pixi workspace register  list                                                         
test-three = "/tmp/test-three"
test-one = "/tmp/test-one"

AI Disclosure

• This PR contains AI-generated content.
  • I have tested any AI-generated content in my PR.
  • I take responsibility for any AI-generated content in my PR.

Tools: {e.g., Claude, Codex, GitHub Copilot, ChatGPT, etc.}

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added sufficient tests to cover my changes.
• I have verified that changes that would impact the JSON schema have been made in schema/model.py.

[baszalmstra]

Thanks @soapy1 ! This is very cool!

I think your arguments are all very reasonable. Note that we choose the argument name to be -n because that is the same shortcut that is used in conda itself, but if that indeed conflicts, we might need to reconsider.

I will let @ruben-arts take a closer look at the UX but he is currently on a skiing trip until the end of the week. I understood from your discord message that you want to redo the PR after the user-experience is more fine-tuned so I held off on reviewing the code itself.

[wolfv]

Awesome stuff!

[ruben-arts]

Hi @soapy1, thanks for your work! I would like to discuss a few parts.

Arguments -b or --workspace-name

I think we could make this -w --workspace instead of anything related to name.
The --name/-n option is still good, I would honestly be fine by removing -n for --dry-run this was a bad decision as we're just to close to conda to not confuse users.

---

The registry name

I feel now i'm typing it that it was a bad proposal. What about pushing it under pixi workspaces (still confusing with pixi workspace) but more descriptive as registry can mean a lot of things.

---

More automation when adding

pixi registry add <name> <path>

This should be automatic to the name of the workspace or directory name, and it should use the current workspace path.
I would make --name and --path an named instead of positional argument.
So that this would work in a workspace:

> pixi registry add
✔  Workspace 'workspace-name' registered successfully.

---

Global workspace location

While sitting next to users that have used conda or other system package managers I see that they dislike the experience of self managing the workspace and it's related files in custom directories. This would help them manage it more easily.

What about this idea:

# Same behavior as now, create a pixi.toml in the current folder
> pixi init

# Same behavior as now, create a pixi.toml in provided folder name
> pixi init workspace-name

# Create a named workspace in the global location (`$HOME/.pixi/workspaces`)
# Similar to conda create
> pixi init -n my-workspace

# Create a pixi.toml in the provided folder and add it to the registry
> pixi init -n dev my-workspace

A second idea would be to add another command, e.g. pixi create. This would do the named workspace workflow. pixi init would not change.

# Copy the `conda env create` command. e.g.:
pixi create -n test python black mkdocs

---

Cleaning

I think it should also have a clean command to cleanup or prune the list of workspaces to avoid empty links.

> pixi init -n test 
> rm -rf test
> pixi run -b test echo

thread 'main2' panicked at crates/pixi_cli/src/cli_config.rs:51:76:
called `Result::unwrap()` on an `Err` value:   × Named workspace 'test' not found

note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

thread 'main' panicked at crates/pixi/src/main.rs:49:10:
Tokio executor failed, was there a panic?: Any { .. }

Also small reminder (not sure if it would be part of the cleanup), never use unwraps or panic, in errors that users may encounter.

[baszalmstra]

I feel now i'm typing it that it was a bad proposal. What about pushing it under pixi workspaces (still confusing with pixi workspace) but more descriptive as registry can mean a lot of things.

I think pixi workspaces is also not great and bound for confusion. pixi workspace registry?

pixi registry add

How about simply pixi workspace register? With optionally a --name?

pixi create -n test python black mkdocs

I think that will be very confusing for people who do not want this flow. Which I still think will be the majority. init vs create is just confusing.

What about:

pixi conda create

or

pixi init --register <optional-target-dir>
# in current dir
pixi init --register
# In target dir
pixi init --register named

[ruben-arts]

How about simply pixi workspace register? With optionally a --name?

I'm fine with that.

I think that will be very confusing for people who do not want this flow. Which I still think will be the majority.

What about pixi workspace create for the conda like experience? I care mostly about the specs and I would dislike a -s/--spec. I would like it to also be able to do pixi workspace create --file env.yaml -n env or something like that. (should not be part of this PR 😉 )

[baszalmstra]

I think if we really want to offer users a similar CLI to conda, we should just add an extra subcommand e.g. pixi conda .... We can use that as an "escape-hatch". Otherwise, we will have some subcommands that are very inconsistent with the rest of the CLI.

So:

pixi conda create ...

The UI should then explain what just happened.

[soapy1]

Thanks @baszalmstra and @ruben-arts for the review on the UX!

Following up on some of your notes:

Arguments -b or --workspace-name

Yep, I agree with your thoughts here. --workspace-name/-b is not very nice. I've updated it to --workspace/-w as suggested.
I also agree that --name/-n would be nice. If we find that --workspace/-w is not good enough, I'm happy to sort out renaming the short flag for --dry-run to remove the collision on the short flag -n.

The registry name

A lot of notes on this point. I'm not quite sure the direction we landed on here? Say pixi workspace register as suggested in #5277 (comment)?

Another important feature of being able to have an association of names to environments is being able to list what the named environments are. For example, in conda we have conda env list/conda info --envs. So, how should pixi surface that information? Maybe pixi workspace register --list or pixi workspace list?

More automation when adding

Good idea, added!

Global workspace location

A few follow up questions about implementation for this approach:

• should users be able to configure the global environments location (for example, conda has the envs_dirs config)
• how does this configuration interact with the detached-environment config. eg. which config wins? are both configs allowed at the same time?

A second idea would be to add another command, e.g. pixi create. This would do the named workspace workflow. pixi init would not change.

Note, conda also has two different commands for creating environments that are slightly different from each other. This creates quite a bit of user confusion.

Cleaning

Good idea! I added pixi config clean --workspaces-registry. Also happy to rename this.

Also small reminder (not sure if it would be part of the cleanup), never use unwraps or panic, in errors that users may encounter.

Aha! Yes, that would be something on my to-do list. You might have already noticed from thumbing through this PR but, I'm certainly out of my element writing Rust code. This is a helpful tip, thanks!

I would like it to also be able to do pixi workspace create --file env.yaml -n env or something like that. (should not be part of this PR 😉)

Aha! We get this for free in this pr. Try out

$ cat env.yaml
dependencies:
  - numpy

$ pixi init --import env.yaml --workspace my-conda-env /tmp/env

This will create a new environment at /tmp/env. Users can access this env with the name my-conda-env. It is equivalent (mostly) to conda env create --file env.yaml --prefix /tmp/env.

I think if we really want to offer users a similar CLI to conda, we should just add an extra subcommand

IMO it's handy to be able to have named environments. And the workflows suggested by conda are good. But, it would be nice for pixi to be able to support this functionality without requiring bringing along the exact conda way of doing things.

Other things to do:

• update the pixi workspace name set command to update the name of the workspace in the registry
• fix error handling

[dhirschfeld]

So, how should pixi surface that information? Maybe pixi workspace register --list or pixi workspace list?

I quite like pixi workspace list but maybe that's confusing with other workspace related commands if it doesn't have some mention of register in the command.

A potential alternative could be pixi workspace --list-registered

[ruben-arts]

I think --workspace/-w is the way to go. If we mix that with pixi workspace register and extend it with: pixi workspace register list pixi workspace register prune pixi workspace register remove etc. It is probably fine for a first iteration.

I'll not focus on the create style command in this PR.

One idea @wolfv and I discussed is that instead of using a configuration file for the registry we could make use of the file system and place symlinks, or a file with a path on platforms that don't support symlinks, to point to workspaces. This way there still is a directory that can be inspected, which can also future prove the effort to add workspaces that don't have a user choosen location.

[soapy1]

Circling back here, got a demo of the pixi workspace register command pushed up, and updated the pr description to reflect the changes made so far.

instead of using a configuration file for the registry we could make use of the file system and place symlinks, or a file with a path on platforms that don't support symlinks, to point to workspaces.

oh, that's a compelling idea! I'm happy to put together a demo (+ notes) for this. I'm a bit slammed the rest of the week, but should be able to get to it pretty soon 💯.

[soapy1]

Ok so, circling back to this! I wrote a few different demos to explore options for how pixi ought to organize the registry. I would like to emphasize that I took a lot of shortcuts writing these demos. The goal was to be able to get a feel for what the limitations for each approach is. There are 3 demo implementations:

• the filesystem idea suggested in the comment soapy1:pixi:named-workspaces-filesystem?expand=1
• the global workspace directory + registry file idea, as suggested in the original proposal soapy1:pixi:named-workspaces-global-workspace-dir?expand=1
• the just registry idea, as suggested originally in this pr soapy1:pixi:named-workspaces-registry-file?expand=1

I wrote up some notes in this google doc if that is helpful.

Going through that exercise, I think a nice solution might be to:

• decoupling the workspace registry and the config.toml is a good option.
  • Slight preference for having a separate workspace registry file. It can lie alongside config.toml as some place like $PIXI_HOME/workspaces.toml. IMO this is a pretty simple and light weight solution.
  • Also important to note, there is maybe more precedence for the symlink solution since the detached environments feature uses this approach.
• not implement pixi init -w <name or workspace> that creates a directory in a global workspace dir (eg. $PIXI_HOME/workspaces/workspace). I think that is a neat extension, and thinking about how that should work should inform this implementation. But I think it adds a lot of UX complexity around deciding when users should be able to create things there/access things from there/etc. For example, this command would do a good job of getting to a similar workflow as the conda create command. But it would be substantially different from the workflow users take with the conda env create command. Maybe it's good to not use conda as the measuring stick for this.

@ruben-arts what are your thoughts?