> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qbraid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# qbraid envs

> Manage Python environments.

Create, install, upload, and share Python environments.
Isolated Python environments with automatic Jupyter kernel integration.
Create environments locally, upload them to the cloud, share with
teammates, or install pre-built environments from the catalog. Works
identically on qBraid Lab and local machines.

Use this when you want to:
• Set up a reproducible Python environment for a project
• Share your environment with collaborators
• Install a pre-configured environment (e.g., qBraid SDK, Qiskit)
• Publish an environment to the public catalog

Quick start:
qbraid envs create # Create new environment
qbraid envs available # Browse installable environments
qbraid envs install \<slug> # Install from cloud
qbraid envs list # List local environments
qbraid envs upload \<name> # Upload to cloud

**Usage**:

```console theme={null}
$ qbraid envs [OPTIONS] COMMAND [ARGS]...
```

**Options**:

* `--help`: Show this message and exit.

**Commands**:

* `create`: Create a new qBraid environment.
* `uninstall`: Remove a local environment.
* `delete`: (Admin) Delete a cloud environment.
* `list`: List installed qBraid environments.
* `activate`: Activate qBraid environment.
* `available`: List installable environments.
* `info`: Show environment details.
* `install`: Install an environment.
* `upload`: Upload an environment.
* `health`: Check the health of an environment.
* `repair`: Repair a broken environment.
* `pythons`: List available Python versions.
* `config`: View or update environment configuration.
* `publish`: Manage environment publishing.
* `share`: Manage environment sharing via share codes.
* `groups`: Manage environment groups.
* `registry`: Manage the local environment registry.

## qbraid envs create

Create a new qBraid environment.

Run without options for an interactive walkthrough, or provide options via flags.

**Usage**:

```console theme={null}
$ qbraid envs create [OPTIONS]
```

**Options**:

* `-n, --name TEXT`: Name of the environment to create
* `-d, --description TEXT`: Short description of the environment
* `-l, --logo TEXT`: Company name for logo (e.g., 'ibm', 'google')
* `-r, --requirements TEXT`: Path to requirements.txt file
* `-k, --kernel-name TEXT`: Display name for Jupyter kernel
* `-t, --tags TEXT`: Comma-separated tags
* `-y, --yes`: Automatically answer 'yes' to all prompts
* `--help`: Show this message and exit.

## qbraid envs uninstall

Remove a local environment.

Removes a qBraid environment from your filesystem.

**Usage**:

```console theme={null}
$ qbraid envs uninstall [OPTIONS]
```

**Options**:

* `-n, --name TEXT`: Name of the environment to remove \[required]
* `-y, --yes`: Automatically answer 'yes' to all prompts
* `--help`: Show this message and exit.

## qbraid envs delete

(Admin) Delete a cloud environment.

Removes the DB entry and storage files.

**Usage**:

```console theme={null}
$ qbraid envs delete [OPTIONS] SLUG
```

**Arguments**:

* `SLUG`: Slug of the cloud environment to delete \[required]

**Options**:

* `-y, --yes`: Automatically answer 'yes' to all prompts
* `--help`: Show this message and exit.

## qbraid envs list

List installed qBraid environments.

**Usage**:

```console theme={null}
$ qbraid envs list [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

## qbraid envs activate

Activate qBraid environment.

NOTE: Currently only works on qBraid Lab platform, and select few other OS types.

**Usage**:

```console theme={null}
$ qbraid envs activate [OPTIONS] NAME
```

**Arguments**:

* `NAME`: Name of the environment. Values from 'qbraid envs list'. \[required]

**Options**:

* `--help`: Show this message and exit.

## qbraid envs available

List installable environments.

Shows available pre-built environments for installation.

**Usage**:

```console theme={null}
$ qbraid envs available [OPTIONS]
```

**Options**:

* `-p, --page INTEGER`: Page number for pagination (default: 1)
* `-l, --limit INTEGER`: Number of environments per page (default: 20)
* `--help`: Show this message and exit.

## qbraid envs info

Show environment details.

Get detailed information about an environment.
Accepts either a local env\_id or a cloud slug. Shows information from
both local registry and cloud catalog when available.

Examples:
$qbraid envs info qiskit_1.0 # By slug (cloud + local if installed)$ qbraid envs info a1b2 # By env\_id (local only)
\$ qbraid envs info my\_custom\_abc123 # Custom environment

**Usage**:

```console theme={null}
$ qbraid envs info [OPTIONS] IDENTIFIER
```

**Arguments**:

* `IDENTIFIER`: Environment identifier (env\_id or slug) \[required]

**Options**:

* `--help`: Show this message and exit.

## qbraid envs install

Install an environment.

Installs a pre-built environment from cloud storage.
If the environment was built for a different platform or requires a Python
version not available on your system, you'll be offered options to either
create a similar local environment or proceed with the download anyway.

**Usage**:

```console theme={null}
$ qbraid envs install [OPTIONS] ENV_SLUG
```

**Arguments**:

* `ENV_SLUG`: Environment slug to install (from 'qbraid envs available') \[required]

**Options**:

* `-t, --temp`: Install as temporary environment (faster, non-persistent)
* `--target TEXT`: Custom target directory (defaults to \~/.qbraid/environments)
* `-y, --yes`: Automatically proceed with default options without prompting
* `--help`: Show this message and exit.

## qbraid envs upload

Upload an environment.

Upload environment to qBraid cloud storage (private by default).
This uploads your local environment to make it available for sharing
with specific users. Use 'qbraid envs publish request' after upload to request
public visibility.

Examples:
$qbraid envs upload my_custom_env$ qbraid envs upload a1b2 --overwrite
$qbraid envs upload my_env --group quantum_sdk$ qbraid envs upload my\_env --slug existing\_slug\_abc123 # Re-upload

**Usage**:

```console theme={null}
$ qbraid envs upload [OPTIONS] IDENTIFIER
```

**Arguments**:

* `IDENTIFIER`: Environment name (if unique) or env\_id to upload \[required]

**Options**:

* `-s, --slug TEXT`: Re-upload to existing slug (replaces previous upload)
* `-g, --group TEXT`: Environment group to add this environment to
* `-o, --overwrite`: Overwrite existing uploaded environment
* `-y, --yes`: Skip confirmation prompts
* `--help`: Show this message and exit.

## qbraid envs health

Check the health of an environment.

This performs comprehensive checks on the virtual environment:

* Python symlinks and executables
* pyvenv.cfg configuration
* Activate scripts
* Kernel configuration (if present)

Examples:
$qbraid envs health my_env$ qbraid envs health a1b2

**Usage**:

```console theme={null}
$ qbraid envs health [OPTIONS] IDENTIFIER
```

**Arguments**:

* `IDENTIFIER`: Environment name or env\_id to check \[required]

**Options**:

* `--help`: Show this message and exit.

## qbraid envs repair

Repair a broken environment.

This attempts to fix common issues:

* Broken Python symlinks
* Invalid pyvenv.cfg paths
* Broken activate scripts
* Invalid kernel.json paths

Use --auto-install to automatically install Python via uv if the
required version is not available.

Examples:
$qbraid envs repair my_env$ qbraid envs repair a1b2 --auto-install

**Usage**:

```console theme={null}
$ qbraid envs repair [OPTIONS] IDENTIFIER
```

**Arguments**:

* `IDENTIFIER`: Environment name or env\_id to repair \[required]

**Options**:

* `-a, --auto-install`: Automatically install Python via uv if needed
* `--help`: Show this message and exit.

## qbraid envs pythons

List available Python versions.

Shows all Python installations found on the system, including:

* System Python (PATH)
* uv-managed Python
* Conda environments
* Homebrew (macOS)
* pyenv installations

Use this to see which Python versions are available for creating
new environments.

Examples:
\$ qbraid envs pythons

**Usage**:

```console theme={null}
$ qbraid envs pythons [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

## qbraid envs config

View or update environment configuration.

Without flags, prints the current config. With flags, applies the updates
and prints the new state. Multiple update flags can be combined in one call.

Examples:
$qbraid envs config 5dcc$ qbraid envs config myenv --description "Quantum sim env"
$qbraid envs config myenv --tags &quot;quantum,sim,gpu&quot;$ qbraid envs config myenv --add-tag gpu --add-tag cuda
$qbraid envs config myenv --remove-tag deprecated$ qbraid envs config myenv --system-site-packages true

**Usage**:

```console theme={null}
$ qbraid envs config [OPTIONS] ENVIRONMENT
```

**Arguments**:

* `ENVIRONMENT`: Environment name, env\_id, or slug \[required]

**Options**:

* `-d, --description TEXT`: Update environment description
* `--tags TEXT`: Replace tags (comma-separated, use '' to clear)
* `--add-tag TEXT`: Append a tag (repeatable)
* `--remove-tag TEXT`: Remove a tag (repeatable)
* `--kernel-name TEXT`: Update Jupyter kernel display name
* `--system-site-packages TEXT`: Enable/disable inheriting packages from parent Python (true/false)
* `--help`: Show this message and exit.

## qbraid envs publish

Manage environment publishing.

**Usage**:

```console theme={null}
$ qbraid envs publish [OPTIONS] COMMAND [ARGS]...
```

**Options**:

* `--help`: Show this message and exit.

**Commands**:

* `request`: Request to publish environment.
* `status`: Check publish status.
* `cancel`: Cancel a pending publish request.
* `review`: (Admin) Mark as under review.
* `approve`: (Admin) Approve and publish.
* `deny`: (Admin) Deny a publish request.

### qbraid envs publish request

Request to publish environment.

Submits your uploaded environment to the public catalog for admin review. Once approved,
it will be publicly visible and installable by all users.

The environment must be uploaded first with 'qbraid envs upload'.

Examples:
\$ qbraid envs publish request my\_env\_abc123

**Usage**:

```console theme={null}
$ qbraid envs publish request [OPTIONS] SLUG
```

**Arguments**:

* `SLUG`: Environment slug (from upload) \[required]

**Options**:

* `--help`: Show this message and exit.

### qbraid envs publish status

Check publish status.

Check the publishing status of an environment.
Status values: - none: Not submitted for publishing - requested: Waiting for admin review - pending: Under admin review - approved: Published to public catalog - denied: Publish request was denied

Examples:
\$ qbraid envs publish status my\_env\_abc123

**Usage**:

```console theme={null}
$ qbraid envs publish status [OPTIONS] SLUG
```

**Arguments**:

* `SLUG`: Environment slug to check \[required]

**Options**:

* `--help`: Show this message and exit.

### qbraid envs publish cancel

Cancel a pending publish request.

This withdraws your publish request before it's approved.
You can resubmit later with 'qbraid envs publish request'.

Examples:
\$ qbraid envs publish cancel my\_env\_abc123

**Usage**:

```console theme={null}
$ qbraid envs publish cancel [OPTIONS] SLUG
```

**Arguments**:

* `SLUG`: Environment slug \[required]

**Options**:

* `--help`: Show this message and exit.

### qbraid envs publish review

(Admin) Mark as under review.

Transitions the environment from 'requested' to 'pending' status,
indicating an admin is actively reviewing it.

Examples:
\$ qbraid envs publish review my\_env\_abc123

**Usage**:

```console theme={null}
$ qbraid envs publish review [OPTIONS] SLUG
```

**Arguments**:

* `SLUG`: Environment slug to review \[required]

**Options**:

* `--help`: Show this message and exit.

### qbraid envs publish approve

(Admin) Approve and publish.

Approve and publish an environment to the public catalog.
This makes the environment publicly visible and installable by all users.
After approval, you'll be prompted to add the environment to a group
if it's not already in one.

Examples:
$qbraid envs publish approve my_env_abc123$ qbraid envs publish approve my\_env\_abc123 --group qiskit
\$ qbraid envs publish approve my\_env\_abc123 --no-group

**Usage**:

```console theme={null}
$ qbraid envs publish approve [OPTIONS] SLUG
```

**Arguments**:

* `SLUG`: Environment slug to approve \[required]

**Options**:

* `-g, --group TEXT`: Add environment to this group after approval
* `--no-group`: Skip the group assignment prompt
* `--help`: Show this message and exit.

### qbraid envs publish deny

(Admin) Deny a publish request.

The owner will be notified with the denial reason.

Examples:
$qbraid envs publish deny my_env_abc123$ qbraid envs publish deny my\_env\_abc123 --message "Missing documentation"

**Usage**:

```console theme={null}
$ qbraid envs publish deny [OPTIONS] SLUG
```

**Arguments**:

* `SLUG`: Environment slug to deny \[required]

**Options**:

* `-m, --message TEXT`: Reason for denial (sent to owner)
* `--help`: Show this message and exit.

## qbraid envs share

Manage environment sharing via share codes.

**Usage**:

```console theme={null}
$ qbraid envs share [OPTIONS] COMMAND [ARGS]...
```

**Options**:

* `--help`: Show this message and exit.

**Commands**:

* `list`: List users with access.
* `create-code`: Generate a share code.
* `delete-code`: Delete the share code for an environment.
* `redeem-code`: Redeem a share code.

### qbraid envs share list

List users with access.

Shows all users with read or write access to the specified environment.

Examples:
\$ qbraid envs share list my\_env\_abc123

**Usage**:

```console theme={null}
$ qbraid envs share list [OPTIONS] SLUG
```

**Arguments**:

* `SLUG`: Environment slug to check \[required]

**Options**:

* `--help`: Show this message and exit.

### qbraid envs share create-code

Generate a share code.

Creates an 8-character code that others can redeem with
'qbraid envs share redeem-code' to gain read access to your environment.
Only the owner can generate codes.

Generating a new code invalidates any previous code for this environment.

Examples:
\$ qbraid envs share create-code my\_env\_abc123
Share code: ABC12XYZ