A netrc file (.netrc or _netrc) is used to hold credentials necessary to login to your LabKey Server and authorize access to data stored there. The netrc file contains authentication for connecting to one or more machines, often used when working with APIs or scripting languages.

Set Up a Netrc File

On a Mac, UNIX, or Linux system the netrc file must be a text file named .netrc (dot netrc). The file should be located in your home directory and the permissions on the file must be set so that you are the only user who can read it, i.e. it is unreadable to everyone else. It should be set to at least Read (400), or Read/Write (600).

On a Windows machine, the netrc file must be a plain text file named _netrc (underscore netrc) and ideally it will also be placed in your home directory (i.e., C:\Users\<User-Name>). You should also create an environment variable called 'HOME' that is set to where your netrc file is located. The permissions on the file must be set so that you are the only user who can read (or write) it. Be sure that this file is not created as a "Text Document" but is a flat file with no extension (extensions may be hidden in the file explorer).

The authentication for each machine you plan to connect to is represented by a group of three definitions (machine, login, password). You can have multiple sets of these definitions in a single netrc file to support connecting to multiple systems. A blank line separates the three definitions for each machine entry you include.

For each machine you want to connect to, the three lines must be separated by either white space (spaces, tabs, or newlines) or commas:

machine <instance-of-labkey-server>
login <user-email>
password <user-password>

The machine is the part of your machine's URL between the protocol designation (http:// or https://) and any port number. For example, both "myserver.trial.labkey.host:8888" and "https://myserver.trial.labkey.host" are incorrect entries for this line.

The following are both valid netrc entries for a user to connect to an instance where the home page URL looks something like: "https://myserver.trial.labkey.host:8080/labkey/home/project-begin.view?":

machine myserver.trial.labkey.host
login user@labkey.com
password mypassword

You could also keep the definitions on one line separating by spaces as in:

machine myserver.trial.labkey.host login user@labkey.com password mypassword

Separate sections for different machines with blank lines, letting you maintain access to several machines in one netrc file:

machine myserver.trial.labkey.host login user@labkey.com password mypassword

machine localhost login user@labkey.com password localboxpassword

Avoid leaving extra newlines at the end of your netrc file. Some applications may interpret these as missing additional entries or premature EOFs.

Use API Keys

When API Keys are enabled on your server, you can generate a specific token representing your login credentials on that server and use it in the netrc file. The "login" name used is "apikey" (instead of your email address) and the unique API key generated is used as the password. For example:

machine myserver.trial.labkey.host login apikey password TheUniqueAPIKeyGeneratedForYou

machine localhost login user@labkey.com password localboxpassword

See API Keys for more information and examples.

Provide Alternative Location for Netrc

If you need to locate your netrc file somewhere other than the default location (such as to enable a dockerized scripting engine) you can specify the location in your code.

In Rlabkey, you could use labkey.setCurlOptions:

Rlabkey::labkey.setCurlOptions(NETRC_FILE = '/path/to/alternate/_netrc')

In Python, you can set CURLOPT_NETRC_FILE:

curl_easy_setopt(curl, CURLOPT_NETRC_FILE, "/path/to/alternate/_netrc");


To test a netrc file using R, create the following R report in RStudio, substituting mylabkeyserver.com/myproject with the name of your actual server and folder path:


If whoAmI returns "guest", this suggests that the netrc file is not authenticating successfully for some reason. If whoAmI returns your username, then the netrc file is working correctly.


If you receive "unauthorized" error messages when trying to retrieve data from a remote server you should first check that:

  1. Your netrc file is configured correctly, as described above.
  2. You've created a HOME environment variable, as described above.
  3. You have a correctly formatted entry for the remote machine you want to access.
  4. The login credentials are correct. When using an API key, confirm that it is still valid and for the correct server.
  5. The API call is correct. You can obtain an example of how to retrieve the desired data by viewing it in the UI and selecting (Export) > Export to Script > Choose the API you want to use.
  6. The netrc file does not have a ".txt" extension. Note that on Windows, extensions are not always displayed in the file explorer. Double check that the "Type of file" (right click the file and choose properties) reads "File" and not "Text Document".

Additional troubleshooting assistance is provided below.

Port Independence

Note that the netrc file only deals with connections at the machine level and should not include a port number or protocol designation (http:// or https://), meaning both "mymachine.labkey.org:8888" and "https://mymachine.labkey.org" are incorrect. Use only the part between the slashes and/or any colon:port.

If you see an error message similar to "Failed connect to mymachine.labkey.org:443; Connection refused", remove the port number from your netrc machine definition.

File Location

An error message similar to "HTTP request was unsuccessful. Status code = 401, Error message = Unauthorized" could indicate an incorrect location for your netrc file. In a typical installation, R will look for libraries in a location like \home\R\win-library. If instead your installation locates libraries in \home\Documents\R\win-library, for example, then the netrc file would need to be placed in \home\Documents instead of the \home directory.

Related Topics

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all