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

# Concepts

pyx organizes users and [packages](#packages) into [teams](#teams),
[workspaces](#workspaces), [registries](#registries), and [views](#views).

## Teams

A **team** is the highest level of organization in pyx. A team contains one or
more [workspaces](#workspaces) and is made up of users of various roles.

Most users will belong to a single team corresponding to your organization, but
you may have multiple teams depending on how your organization is using pyx.

When you log into the [pyx dashboard](https://app.pyx.dev), you'll be
interacting with a specific team's resources. You can switch between teams at
log-in time, or by using the team switcher in the top-left corner of the
dashboard.

## Workspaces

A **workspace** hosts [registries](#registries) and [views](#views). It has a
name for easy reference. You can have multiple workspaces in a team, which helps
group related registries and views together under a shared name.

Workspaces are a way to group related registries together. For example, the
[GPU workspace](https://app.pyx.dev/workspace/astral-sh) contains distinct
registries for different CUDA, ROCm, and other GPU configurations.

A common use case for workspaces is deployment isolation. For example, your team
might choose to have separate `development`, `staging`, and `production`
workspaces.

Beyond the workspaces owned by your team, there are also "global" workspaces to
which all teams have read access. These include the GPU workspace (`astral-sh`)
and the PyPI workspace (`public`).

## Registries

A **registry** is a named index of packages. Each registry has a default
[view](#views) with the same name, which provides read access to the registry's
packages via the standard
[Simple Repository APIs](https://packaging.python.org/en/latest/specifications/simple-repository-api/).

By default, every workspace has a default registry named `main`. You can access
your workspace's default registry through `/simple/acme/main` and publish to it
using `/v1/upload/acme/main`, where `acme` is your team name.

When [publishing](/publishing) packages, you do so to a specific registry (or to
the default registry for the workspace).

## Views

<Note>
  See [Custom views](/views) for additional documentation on creating and using
  views and view filters.
</Note>

A **view** is a named combination of [registries](#registries), exposed as a
single index URL. You can use views to compose multiple registries together into
a single developer-facing index. Views can also be configured with custom
filters that restrict their underlying packages.

## Packages

<Tip>
  Packages are also sometimes referred to as "projects".

  A package on pyx is analogous to a project on PyPI.
</Tip>

A **package** is a named collection of [releases](#releases), their constituent
[files](#files), and associated metadata. Package names are unique within a
given [registry](#registries), and are
[standardized](https://packaging.python.org/en/latest/specifications/name-normalization/).

Examples of packages include `uv`, `cryptography`, `numpy`, and `urllib3`.

## Releases

A **release** is a specific version of a [package](#packages), identified by a
standardized
[version specifier](https://packaging.python.org/en/latest/specifications/version-specifiers/).
Every release has zero or more associated [files](#files) that can be installed.

When installing dependencies, releases are often selected with version
constraints, e.g. `cryptography==44` for exactly version 44 of the
`cryptography` package, or `numpy>=1.25` for any version of `numpy` greater than
or equal to 1.25.

## Files

<Tip>Files are also sometimes referred to as "distributions".</Tip>

A **file** is a single installable archive for a specific [release](#releases)
of a [package](#packages).

There are two primary kinds of files:

* Source distributions (sdists): These are `.tar.gz` archives that contain the
  source code for a package release. They can be installed on any platform,
  provided that they build successfully when installed.
* Built distributions (wheels): These are ZIP archives with the `.whl` extension
  that don't require a build step at install time. Wheels may be
  platform-specific, and installers like [uv](https://docs.astral.sh/uv/) will
  fetch the appropriate wheel for the target platform when installing.

In general, installers will prefer wheels over sdists when both are available.

Because wheels can be platform-specific, a single release of a package often has
multiple wheels associated with it, each targeting a different platform or
Python version. Conversely, a source distribution is platform-agnostic, so there
is only one sdist per release.