Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 CLI Reference | 2025.1

# p4 unload

Unloads a workspace, label, or task stream to the unload depot or to a flat file.

## Syntax

    p4 [g-opts] unload [-f -L -p -z] [-c client | -l label | -s stream]
    p4 [g-opts] unload [-f -L -z] [-a | -al | -ac] [-d date | -u user]

Syntax conventions

## Description

Two uses for the `p4 unload` command are:

To transfer infrequently-used metadata from P4 Server db.* files to a set of flat files in the unload depot | To unload a client, label, or task stream to a flat file on the client
--- | ---
P4 Server reporting commands often retrieve a superset of the desired data, and then users take advantage of automated or manual post-processing to discard the irrelevant lines of output. For example, the `p4 clients` command (when called without arguments) returns the name of every client workspace ever created by every current and former employee of your organization, even those who left years ago. Unloading metadata reduces the size of the working set required by P4 Server. On large sites with many years of historical metadata, unloading can offer significant performance improvements, reduce the output of the command-line queries and the amount of information displayed in applications like P4V P4 Server commands such as `p4 clients`, `p4 labels`, `p4 files`, `p4 sizes`, and `p4 fstat` ignore unloaded metadata. To view metadata that has been unloaded, use the `-U` option with these commands. | This is useful for seeding a client into another database, or for creating a private backup of the client. The flat file uses the standard journal format. The client, label, or task stream remains fully loaded after the command is run. Requires the -o Option.

Use the `-c` and `-l` options to unload a specific client workspace or label. Users can only unload their own workspaces or labels. Administrators can use the `-f` option to unload workspaces and labels owned by other users.

You do not need to unload a workspace in preparation for moving it from one edge server to another because running the `p4 reload` command automatically unloads the specified workspace before reloading it into a new edge server.

Use the `-a`, `-al`, or `-ac` options to indicate that all specified labels and/or client workspaces are to be unloaded. You cannot use these options if you are also using the `-o` option.

Use the `-d date` and/or `-u user` to restrict the unloading operation to labels and/or workspaces older than a specific `date`, owned by a specific `user`, or both.

Use the `-L` option to unload locked workspaces and/or labels. By default, only unlocked labels or workspaces are unloaded.

The access date for a workspace is updated when:

- the workspace is used by a command that directly references the workspace. These commands include: p4 add, p4 change, p4 delete, p4 diff, p4 edit, p4 have, p4 integrate, p4 labelsync, p4 lock, p4 move, p4 opened, p4 reconcile, p4 reopen, p4 resolve, p4 revert, p4 shelve, p4 submit, p4 sync, p4 unshelve, and p4 where
- the workspace is used in a revision specifier of the form `@`workspace``.

Running p4 client does NOT update the access time, only the client Update time if the client spec is edited and saved.

The access date for a label is updated when:

- the label is used by a command that directly references that label.
- the label is used in a revision specifier of the form `@`labelname``.

By default, data in the unload depot is uncompressed. Use `-z` to store it in compressed form. Unloaded metadata is often highly compressible, particularly in continuous build environments characterized by millions of build-associated workspaces labels that are used to perform a single build and then rarely, if ever, accessed again.

## Options

`-a` | Unload all applicable client workspaces and labels; requires `-d`, `-u`, or both `-d` and `-u` options. This option does not affect task streams.
`-ac` | Unload client workspaces; requires `-d`, `-u`, or both `-d` and `-u` options.
`-al` | Unload labels; requires `-d`, `-u`, or both `-d` and `-u` options.
`-c client` | Unload the specified client workspace’s metadata from `db.have` (and related tables) and store it in the unload depot.
`-d date` | Unload metadata older than the specified date.
`-f` | Force option; administrators can unload workspaces, labels, and task streams owned by other users.
`-l label` | Unload the specified label from `db.label` (and related tables) and store it in the unload depot.
`-L` | Unload a `locked` workspace, label, or task stream.
`-p` | Promote any non-promoted shelves belonging to the specified client that is being unloaded. The shelf is promoted to the commit server where it can be accessed by other edge servers.
`-s stream` | Unload the specified task stream. Note that the `stream` must be of type `task`.
`-u user` | Unload metadata owned by the specified user.
`-z` | Store the unloaded workspace, label, or task stream in compressed format.
`g-opts` | See Global options.

## Usage Notes

Can File Arguments Use Revision Specifier? | Can File Arguments Use Revision Range? | Minimal Access Level Required
--- | --- | ---
No | No | `write` `admin`

- To unload a workspace or label, a user must be able to scan all the files in the workspace’s have list The list of file revisions most recently synced from the depot into the workspace. In other words, the list of files that the client workspace has. and/or files tagged by the label. Administrators should set `MaxScanRows` and `MaxResults` high enough (in the `p4 group` form) that users do not need to ask for assistance with `p4 unload` or `p4 reload` operations.

## Related commands

To reload data from the unload depot. | `p4 reload`

Your search for returned results