Skip to main content

Documentation Index

Fetch the complete documentation index at: https://flox.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
NAME

flox-pull - pull environment from FloxHub

​
SYNOPSIS

# 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(1). 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(1). 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(1). See manifest.toml(5) 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(1) flox-edit(1) manifest.toml(5)