feat: allow users to use Pixi named workspaces through a registry by soapy1 · Pull Request #5277 · prefix-dev/pixi

soapy1 · 2026-01-12T22:23:50Z

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. Defaults to the name of the current workspace
  -p, --path <PATH>  Path to register. Defaults to the path to the current workspace
  -f, --force        Overwrite the workspace entry if the name of the workspace already exists in the registry

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 myworkspace2 -p /path/to/my/project

Registering a workspace with a name that is already registered will not not update the registry. Users can provide the --force flag to force this behaviour.

$ pixi workspace register -n myworkspace -p /path/to/other/project   
❌  Workspace already exists. Use the `--force` flag to overwrite a named workspace.

$ pixi workspace register -n myworkspace -p /path/to/other/project  --force
✔  Workspace registered successfully.

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.

Argument name

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

Other notes

Creating a new globally named workspace is not included in this PR. There are some good options as to how the UX for this should look. But, this maybe needs some more discussion and can be implemented in another PR.

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 name set test-one
$ pixi workspace register
✔  Workspace registered successfully.

# list available registered environments
$ workspace register list 
test-one = "/tmp/test-one"

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: pixi run --manifest-path <MANIFEST_PATH> [TASK]...

For more information, try '--help'.

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

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

[tasks]

[dependencies]
python = "3.14.*"
flask = ">=3.1.3,<4"

# run python from the test-one environment
$ pixi run -w test-one -- 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-two"
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 workspace register --name test-two --path /tmp/test-two   
✔  Workspace registered successfully.
# alternatively, register using the `--manifest-path` argument to take the name from the provided path
# pixi workspace register -m /tmp/test-two   

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

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

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

Remove a workspace from the registry

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


# 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-one = "/tmp/test-one"

Using a workspace that doesn't exist

$ pixid list -w idontexist                                                                                                                                             
Error:   × could not find workspace 'idontexist'

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 · 2026-01-13T08:25:39Z

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 · 2026-01-13T19:39:21Z

Awesome stuff!

ruben-arts · 2026-01-20T15:38:40Z

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 · 2026-01-20T15:56:04Z

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 · 2026-01-20T16:18:30Z

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 · 2026-01-20T16:24:36Z

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 · 2026-01-21T02:30:00Z

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 · 2026-01-21T13:38:54Z

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 · 2026-01-21T14:24:37Z

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 · 2026-01-22T03:48:57Z

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 · 2026-01-27T20:43:53Z

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?

ruben-arts · 2026-02-06T12:48:14Z

Hey @soapy1, amazing work on the R&D! Would you be open to discuss this in real time? I send you a message on Discord.

This allows for adding a new type of `DiscoverStart` that uses the workspace registry to find the pixi manifest.

Co-authored-by: Ruben Arts <ruben.arts@pm.me>

dhirschfeld · 2026-03-14T23:54:15Z

I'm super excited for this functionality to land! 🚀

Thanks @soapy1 for implementing this, and @ruben-arts for all the reviews to get it to this stage! ❤️

Just bumping this PR in the hope that it can make the next release 🙏

ruben-arts

Thank you @soapy1!

I'm going to merge it now, sorry for the huge delay, the PR got burried by other work.

You did a great job, nice working with you. I would love to see a followup PR to add more documentation e.g. in https://pixi.prefix.dev/latest/switching_from/conda/

But I'm not holding this PR back on it. Thanks @dhirschfeld for the ping!

soapy1 · 2026-03-18T01:13:47Z

Yay! Thanks for all your guidance here @ruben-arts and pixi team/community 🙌 I got a little follow up docs pr here #5720

soapy1 changed the title ~~Demo: Allow users to use Pixi named workspaces through a registry~~ feat: (demo) allow users to use Pixi named workspaces through a registry Jan 12, 2026

soapy1 force-pushed the named-workspaces branch 2 times, most recently from 4cdee0b to 10d0a0f Compare January 12, 2026 23:44

aktech mentioned this pull request Jan 14, 2026

Add nebi CLI tool nebari-dev/nebi#5

Closed

ruben-arts self-requested a review January 20, 2026 10:22

soapy1 force-pushed the named-workspaces branch from 10d0a0f to 8a728a6 Compare January 21, 2026 01:38

Adam-D-Lewis mentioned this pull request Jan 21, 2026

Consider Centralized Storage of Nebi Workspaces nebari-dev/nebi#16

Open

soapy1 force-pushed the named-workspaces branch from 0adf4b2 to 1376c6a Compare January 22, 2026 01:05

soapy1 force-pushed the named-workspaces branch from ee3662d to 15fc2ce Compare January 27, 2026 18:22

soapy1 force-pushed the named-workspaces branch from d070d91 to e0f5434 Compare January 29, 2026 20:38

soapy1 force-pushed the named-workspaces branch 5 times, most recently from 6fe6c75 to dac968d Compare February 21, 2026 01:17

soapy1 force-pushed the named-workspaces branch 3 times, most recently from 8be4828 to 075bd07 Compare February 23, 2026 06:11

soapy1 and others added 14 commits February 24, 2026 17:27

Back out registering a workspace as part of initialization

c7ae89a

Add workspace registry module

1cf250b

Add workspace registry module

982ae08

Update workspace register command

b78e572

Update workspace discovery to use workspace registry file

758656f

fmt

2eb1ec8

Back out workspace registry information in pixi global config

73d37ea

Re-add prune registry command

f47cef8

Regenerate docs

2caebd0

Allow users to force overwriting an entry in the workspace registry

94d78f5

Add unit tests

76c49ba

Refactor: move workspace registry to core

efeef12

This allows for adding a new type of `DiscoverStart` that uses the workspace registry to find the pixi manifest.

Update crates/pixi_core/src/workspace/registry.rs

4089da1

Co-authored-by: Ruben Arts <ruben.arts@pm.me>

Back out test related to removed config changes

b16b773

soapy1 force-pushed the named-workspaces branch from 4aa80fb to 69d05eb Compare February 25, 2026 08:00

soapy1 added 2 commits February 25, 2026 00:09

Output help if the user provides a workspace that is not in the registry

b62bcc0

Add error message for if a workspace path no longer exists

9713bf0

soapy1 force-pushed the named-workspaces branch from 69d05eb to 9713bf0 Compare February 25, 2026 08:10

soapy1 and others added 4 commits February 25, 2026 00:49

Propagate workspace not found error messages

a6de563

Merge branch 'main' into named-workspaces

b137b89

Merge branch 'main' into named-workspaces

7d10122

Return WorkspaceLocatorErorr when unable to find workspace

eb9cb21

soapy1 force-pushed the named-workspaces branch from 0fd05ef to eb9cb21 Compare March 4, 2026 16:06

soapy1 requested a review from ruben-arts March 5, 2026 14:34

ruben-arts approved these changes Mar 16, 2026

View reviewed changes

ruben-arts merged commit a210067 into prefix-dev:main Mar 16, 2026
41 checks passed

BrewTestBot mentioned this pull request Mar 17, 2026

pixi 0.66.0 Homebrew/homebrew-core#272815

Merged

soapy1 mentioned this pull request Mar 18, 2026

docs: Add named workspaces notes for conda users #5720

Open

1 task

Conversation

soapy1 commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Key changes

pixi workspace register command

Cleaning up the registry of workspaces

Argument name

Other notes

How Has This Been Tested?

Register an existing pixi project

Use a named workspace

Use a named workspace with multiple environments

Remove a workspace from the registry

Using a workspace that doesn't exist

AI Disclosure

Checklist:

Uh oh!

baszalmstra commented Jan 13, 2026

Uh oh!

wolfv commented Jan 13, 2026

Uh oh!

ruben-arts commented Jan 20, 2026

Arguments -b or --workspace-name

The registry name

More automation when adding

Global workspace location

Cleaning

Uh oh!

baszalmstra commented Jan 20, 2026

Uh oh!

ruben-arts commented Jan 20, 2026 • edited by baszalmstra Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

baszalmstra commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

soapy1 commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Other things to do:

Uh oh!

dhirschfeld commented Jan 21, 2026

Uh oh!

ruben-arts commented Jan 21, 2026

Uh oh!

soapy1 commented Jan 22, 2026

Uh oh!

soapy1 commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ruben-arts commented Feb 6, 2026

Uh oh!

dhirschfeld commented Mar 14, 2026

Uh oh!

ruben-arts left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

soapy1 commented Mar 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

soapy1 commented Jan 12, 2026 •

edited

Loading

`pixi workspace register` command

Arguments `-b` or `--workspace-name`

The `registry` name

ruben-arts commented Jan 20, 2026 •

edited by baszalmstra

Loading

baszalmstra commented Jan 20, 2026 •

edited

Loading

soapy1 commented Jan 21, 2026 •

edited

Loading

soapy1 commented Jan 27, 2026 •

edited

Loading