> ## Documentation Index
> Fetch the complete documentation index at: https://flox-daniel-dev-89-update-auto-activate-docs-man-pages.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# flox pull

## NAME

flox-pull - pull environment from FloxHub

## SYNOPSIS

```text theme={null}
# Pull a new environment into a directory
flox [<general-options>] pull <owner>/<name>
     [-d=<path>]
     [-f]
     [-c]
     [-g=<generation>]

# Update an existing environment in a directory
flox [<general-options>] pull
     [-d=<path>]
     [-f]

# Fetch updates for a remote environment
flox [<general-options>] pull -r <owner>/<name>
     [-f]
```

## DESCRIPTION

Pull an environment from FloxHub and create a local reference to it, or,
if an environment has already been pulled, retrieve any updates.

### Pulling a new environment (`<owner>/<name> [--dir <dir>]`)

Create an environment in the current directory or the directory
specified by the `--dir` flag, that is linked to the centrally managed
environment `<owner>/<name>` on FloxHub. You can make changes locally
and push them back with [`flox-push`](/man/flox-push).

Alternatively, the `--copy` flag allows you to create an environment,
but does not link it to its upstream on FloxHub. Optionally, the
`--generation <generation>` can be used to select a specific generation
to create a copy of.

### Updating an existing environment in a directory (`[--dir]`)

Without a `<owner>/<name>` argument, updates an environment that has
already been pulled into the current directory, or the directory
specified by the `--dir` flag .

`-f` may be specified to forcibly update the environment locally even if
there are local changes not reflected in the remote environment.

### Updating FloxHub environments (`--reference <owner>/<name>`)

When using the `--reference` flag, commands will operate on a copy of
the environment stored in Flox’s cache directory. Any changes made to an
environment using the `--reference` flag, affect only the local copy and
must be explicitly updated on FloxHub using
[`flox-push`](/man/flox-push).

`flox pull --reference <owner>/<name>` will create such a local copy for
the specified environment, or update an existing copy. This allows you
to work offline with cached environments and only sync when you choose
to.

### Platform Support

A remote environment may not support the architecture or operating
system of the local system pulling the environment, in which case `-f`
may be passed to forcibly add the current system to the environment’s
manifest. This may create a broken environment that cannot be pushed
back to FloxHub until it is repaired with
[`flox-edit`](/man/flox-edit). See
[`manifest.toml`](/man/manifest.toml) for more on multi-system
environments.

## OPTIONS

### Pull Options

`-d`, `--dir`\
Directory to pull an environment into, or directory that contains an
environment that has already been pulled (default: current directory).

Cannot be used with `--reference`.

`<owner>/<name>`\
Reference of an environment to pull into a directory

This is used when pulling a new environment for the first time.

`-f`, `--force`\
Forcefully overwrite the local copy of the environment, and accept any
kind of modification and possibly incompatible results that have to be
addressed manually.

`-c`, `--copy`\
Create a local copy of an environment by removing the connection to the
upstream environment on FloxHub. When pulling a new environment this
creates a new environment that can be used locally or pushed to FloxHub
under a new user or name.

`-g <generation>`, `--generation <generation>`\
Pull the specified generation instead of the live generation. Must be
used with `--copy`.

`-r <owner>/<name>`, `--reference <owner>/<name>`\
Pull updates for a local copy of a FloxHub environment

The pulled environment can be used by passing `--reference` to other
subcommands.

This updates a FloxHub environment that has been activated or pulled
locally and is cached in `~/.cache`.

Cannot be used with `--dir`, `--copy`, or `--generation`.

### General Options

`-h`, `--help`\
Prints help information.

The following options can be passed when running any `flox` subcommand
but must be specified *before* the subcommand.

`-v`, `--verbose`\
Increase logging verbosity. Invoke multiple times for increasing detail.

`-q`, `--quiet`\
Silence logs except for errors.

## SEE ALSO

[`flox-push`](/man/flox-push) [`flox-edit`](/man/flox-edit)
[`manifest.toml`](/man/manifest.toml)